mumuki-puzzle-runner

Install the server

bundle install

Run the server

RACK_ENV=development rackup -p 4567

Updating the docs

You will need instaling jsdoc-to-markdown first

npm install --global jsdoc-to-markdown

jsdoc2md lib/public/js/muzzle.js 2>&1

Test format

Basic puzzle

Muzzle.basic(3, 2, 'https://flbulgarelli.github.io/headbreaker/static/berni.jpg');

Match-pairs puzzle

const baseUrl = 'https://raw.githubusercontent.com/MumukiProject/mumuki-guia-gobstones-alternativa-kids/master/assets/attires/';

// with left and right pieces
Muzzle.match([
  `${baseUrl}/va_vacio.png`,
  `${baseUrl}/cu_vacio.png`,
  `${baseUrl}/chips_poco.png`
], [
  `${baseUrl}/va_fru.png`,
  `${baseUrl}/cu_vai.png`,
  `${baseUrl}/chips_mucho.png`,
]);

// with left and right pieces, and left odd pieces
Muzzle.match([
  `${baseUrl}/va_vacio.png`,
  `${baseUrl}/cu_vacio.png`,
  `${baseUrl}/chips_poco.png`
], [
  `${baseUrl}/va_fru.png`,
  `${baseUrl}/cu_vai.png`,
  `${baseUrl}/chips_mucho.png`,
], [
  `${baseUrl}/choc_mitad_vacio2.png`
]);

// with left and right pieces, and right odd pieces
Muzzle.match([
  `${baseUrl}/va_vacio.png`,
  `${baseUrl}/cu_vacio.png`,
  `${baseUrl}/chips_poco.png`
], [
  `${baseUrl}/va_fru.png`,
  `${baseUrl}/cu_vai.png`,
  `${baseUrl}/chips_mucho.png`,
],
[], [
  `${baseUrl}/choc_mitad_vacio2.png`
]);

Solution format

The solution accepted by this runner is a JSON string with the following format:

{
  "positions": [
    [10, 20],
    [15, 20],
    [20, 20],
    [10, 25],
    [15, 25],
    [20, 25]
  ]
}:

Muzzle API 💪

Classes

MuzzleCanvas

Facade for referencing and creating a global puzzle canvas, handling solutions persistence and submitting them

Functions

another(id) ⇒ MuzzleCanvas

Creates a suplementary canvas at the element of the given id

Typedefs

PieceConfig : object

Point : Array.<number>

Solution : object

MuzzleCanvas

Facade for referencing and creating a global puzzle canvas, handling solutions persistence and submitting them

Kind: global class

• MuzzleCanvas
  • .canvasId : string
  • .expectedRefsAreOnlyDescriptive : boolean
  • .canvasWidth : number
  • .canvasHeight : number
  • .borderFill : number
  • .strokeWidth : number
  • .pieceSize : number
  • .scaleImageWidthToFit : boolean
  • .previousSolutionContent : string
  • .baseConfig
  • .canvas ⇒ Canvas
  • .solution ⇒ Solution
  • .solutionContent
  • .clientResultStatus ⇒ "passed" | "failed"
  • .onReady()
  • .onSubmit(submission)
  • .onValid()
  • .draw()
  • .expect(refs)
  • .basic(x, y, imagePath) ⇒ Promise.<Canvas>
  • .multi(x, y, [imagePaths]) ⇒ Promise.<Canvas>
  • .match(leftUrls, rightUrls, leftOddUrls, rightOddUrls) ⇒ Promise.<Canvas>
  • .custom(canvas) ⇒ Promise.<Canvas>
  • .ready()
  • .loadSolution(solution)
  • .loadPreviousSolution()
  • .submit()

muzzleCanvas.canvasId : string

The id of the HTML element that will contain the canvas Override it you are going to place in a non-standard way

Kind: instance property of MuzzleCanvas

muzzleCanvas.expectedRefsAreOnlyDescriptive : boolean

Wether expected refs shall be ignored by Muzzle.

They will still be evaluated server-side.

Kind: instance property of MuzzleCanvas

muzzleCanvas.canvasWidth : number

Width of canvas

Kind: instance property of MuzzleCanvas

muzzleCanvas.canvasHeight : number

Height of canvas

Kind: instance property of MuzzleCanvas

muzzleCanvas.borderFill : number

Size of fill. Set null for perfect-match

Kind: instance property of MuzzleCanvas

muzzleCanvas.strokeWidth : number

Canvas line width

Kind: instance property of MuzzleCanvas

muzzleCanvas.pieceSize : number

Piece size

Kind: instance property of MuzzleCanvas

muzzleCanvas.scaleImageWidthToFit : boolean

• Whether image's width should be scaled to piece

Kind: instance property of MuzzleCanvas

muzzleCanvas.previousSolutionContent : string

The previous solution to the current puzzle in a past session, if any

Kind: instance property of MuzzleCanvas

muzzleCanvas.baseConfig

Kind: instance property of MuzzleCanvas

muzzleCanvas.canvas ⇒ Canvas

The currently active canvas, or null if it has not yet initialized

Kind: instance property of MuzzleCanvas

muzzleCanvas.solution ⇒ Solution

The state of the current puzzle expressed as a Solution object

Kind: instance property of MuzzleCanvas

muzzleCanvas.solutionContent

The current solution, expressed as a JSON string

Kind: instance property of MuzzleCanvas

muzzleCanvas.clientResultStatus ⇒ "passed" | "failed"

The solution validation status

Kind: instance property of MuzzleCanvas

muzzleCanvas.onReady()

Callback that will be executed when muzzle has fully loaded and rendered its first canvas.

It does nothing by default but you can override this property with any code you need the be called here

Kind: instance method of MuzzleCanvas

muzzleCanvas.onSubmit(submission)

Callback to be executed when submitting puzzle.

Does nothing by default but you can override it to perform additional actions

Kind: instance method of MuzzleCanvas

Param	Type
submission	Object

muzzleCanvas.onValid()

Callback that will be executed when muzzle's puzzle becomes valid

It does nothing by default but you can override this property with any code you need the be called here

Kind: instance method of MuzzleCanvas

muzzleCanvas.draw()

Draws the - previusly built - current canvas.

Prefer {@code this.currentCanvas.redraw()} when performing small updates to the pieces.

Kind: instance method of MuzzleCanvas

muzzleCanvas.expect(refs)

Kind: instance method of MuzzleCanvas

Param	Type
refs	Array.<Point>

muzzleCanvas.basic(x, y, imagePath) ⇒ Promise.<Canvas>

Creates a basic puzzle canvas with a rectangular shape and a background image, that is automatically submitted when solved

Kind: instance method of MuzzleCanvas Returns: Promise.<Canvas> - the promise of the built canvas

Param	Type	Description
x	number	the number of horizontal pieces
y	number	the number of vertical pieces
imagePath	string

muzzleCanvas.multi(x, y, [imagePaths]) ⇒ Promise.<Canvas>

Kind: instance method of MuzzleCanvas Returns: Promise.<Canvas> - the promise of the built canvas

Param	Type
x	number
y	number
[imagePaths]	Array.<string>

muzzleCanvas.match(leftUrls, rightUrls, leftOddUrls, rightOddUrls) ⇒ Promise.<Canvas>

Craates a match puzzle, where left pieces are matched against right pieces, with optional odd left and right pieces that don't match

Kind: instance method of MuzzleCanvas Returns: Promise.<Canvas> - the promise of the built canvas

Param	Type	Description
leftUrls	Array.<string>
rightUrls	Array.<string>	must be of the same size of lefts
leftOddUrls	Array.<string>
rightOddUrls	Array.<string>

muzzleCanvas.custom(canvas) ⇒ Promise.<Canvas>

Kind: instance method of MuzzleCanvas Returns: Promise.<Canvas> - the promise of the built canvas

Param	Type
canvas	Canvas

muzzleCanvas.ready()

Mark Muzzle as ready, loading previous solution and drawing the canvas

Kind: instance method of MuzzleCanvas

muzzleCanvas.loadSolution(solution)

Loads - but does not draw - a solution into the canvas.

Kind: instance method of MuzzleCanvas

Param	Type
solution	Solution

muzzleCanvas.loadPreviousSolution()

Loads - but does not draw - the current canvas with the previous solution, if available.

Kind: instance method of MuzzleCanvas

muzzleCanvas.submit()

Submits the puzzle to the bridge, validating it if necessary

Kind: instance method of MuzzleCanvas

another(id) ⇒ MuzzleCanvas

Creates a suplementary canvas at the element of the given id

Kind: global function

Param	Type
id	string

PieceConfig : object

Kind: global typedef Properties

Name	Type
imagePath	string
structure	string

Point : Array.<number>

Kind: global typedef

Solution : object

Kind: global typedef Properties

Name	Type	Description
positions	Array.<Point>	list of points