jigsaw_puzzles docs
---------------------------------------------------


/*	  (2021-02-07)
INPUT: 
	- ROM EDITOR DATA -
	{ROM.jigsawPuzzle}			(internally referenced as "jigsawInfo")		Read-only information about all puzzles that exist in this game.  This data is created by the level editor.
		[puzzles]
			0:	[0, 1,2,3,4]
				0 = path\to\finished\puzzle\image.jpg
				1,2,3,4 = piece\image\path.png
		background
		numPieces
		overlap
	
	
	 - RAM GAME DATA -
	{RAM.jigsawPuzzles}			(internally referenced as "jigsawState")		Writable info about which pieces the player currently has,  their position in this UI,  and which puzzles have been completed.  This data is created by the running game.
		{havePieces}
			"0_0"		=  true
			"0_2"		=  true
			"1_1"		=  true
			"1_2"		=  true
		{pieceStates}
			"0_0"		=		{x_tile,y_tile}
			"1_1"		=		{x_tile,y_tile}
		[puzzleStates]
			0:	null
			1:	{x_tile,y_tile}
			2:	null
				(each index corresponds to a puzzle)



RAM VARIABLES

Keyboard control
 ACTION			 RAM VARIABLE			DEFAULT
up				= RAM.key.up		|| Key.UP;
down			= RAM.key.down	|| Key.DOWN;
left			= RAM.key.left	|| Key.LEFT;
right			= RAM.key.right	|| Key.RIGHT;
interact	= RAM.keys.talk	|| Key.ENTER;



PUBLIC INIT PROPERTIES:
	uid								(optional)	defaults to -1
	jigsawInfo				(optional)	defaults to { puzzles=[[0="",1="",2="",3="",4=""]], background="", numPieces=4, overlap=0 }
	jigsawState				(optional)	defaults to { havePieces={}, pieceStates={}, puzzleStates=[] }
	tileSize					(optional)	defaults to 32
	background				(optional)	defaults to ""

	
	
PUBLIC PROPERTIES:
	keyboardControl		= t / f



PUBLIC FUNCTIONS: 
	setSize()					Tell this movieClip what size to use before starting.
	start()						Tell this movieClip it's safe to run early.  Normally it "animates" until frame 2, giving external cde time to talk to it.  Then stops on frame 2.
	update()					add new pieces  +  remove missing pieces
										add new finished puzzles  +  remove incomplete puzzles
	enableKeyboard()
	disableKeyboard()
	addPiece( pieceId, x_tile, y_tile )
	removePiece( pieceId )
	addPuzzle( puzzleIndex, x_tile, y_tile )
	removePuzzle( puzzleIndex )
	movePiece( pieceId, x_tile, y_tile )
	movePuzzle( puzzleId, x_tile, y_tile )
	lockPiece( pieceId )
	unlockPiece( pieceId )
	lockPuzzle( puzzleId )
	unlockPuzzle( puzzleId )
	


PUBLIC EVENTS SENT TO ROOT: 
	ROOT
		jigsaw:dropPiece												Fires after successfully dropping a piece and storing its new position
			{uid, pieceId, tile}
		jigsaw:dropPuzzle												Fires after successfully dropping a puzzle and storing its new position
			{uid, puzzleId, tile, topLeftTile}
		jigsaw:puzzleComplete										Fires after a puzzle has been completed
			{uid, puzzleId, tile, topLeftTile}
	
			
			
PUBLIC EVENTS RECEIVED FROM ROOT: 
		jigsaw:update
		jigsaw:enableKeyboard
		jigsaw:disableKeyboard
		jigsaw:addPiece
			{uid, pieceId, x_tile, y_tile}
		jigsaw:removePiece
			{uid, pieceId}
		jigsaw:addPuzzle
			{uid, puzzleId, x_tile, y_tile}
		jigsaw:removePuzzle
			{uid, puzzleId}
		jigsaw:movePiece
			{uid, pieceId, x_tile, y_tile}
		jigsaw:movePuzzle
			{uid, puzzleId, x_tile, y_tile}
		jigsaw:lockPiece
			{uid, pieceId}
		jigsaw:unlockPiece
			{uid, pieceId}
		jigsaw:lockPuzzle
			{uid, puzzleId}
		jigsaw:unlockPuzzle
			{uid, puzzleId}
		jigsaw:takeMovieClip
			{uid, mcPath, seconds}



INTERNAL EVENTS: 
	puzzleComplete		{puzzleId: #, topLeftTile: {x, y}, tile: topLeftTile}
	enableKeyboard		Activates the cursor and keyboard reactions
	disableKeyboard		Disables the cursor and keyboard reactions
	key:up						Fires when then the UP key is pressed,  if keyboard is active
	key:down					Fires when then the DOWN key is pressed,  if keyboard is active
	key:left					Fires when then the LEFT key is pressed,  if keyboard is active
	key:right					Fires when then the RIGHT key is pressed,  if keyboard is active
	key:act						Fires when then the ENTER key is pressed,  if keyboard is active
	cursorMove				Tells the cursor to move a location.		{pixel, tile}
	liftObject				Tells the cursor to lift an object
	tryDropObject			Asks the object to attempt a drop
	dropObject				Fires when the cursor has successfully dropped an object



puzzle-piece movieClips: 
	is_piece						Boolean flag used to indicate that this as a puzzle-piece
	id									String containing this piece's unique identifier consisting of:  puzzleIndex_pieceIndex		ex: "0_1"
	file								String containing the path to the image file for how this puzzle-piece looks
	image_mc						MovieClip displaying this piece's image
	clickArea						MovieClip representing the clickable/draggable hit-rectangle of this piece
	snapToTile()				Function that moves this piece to the specified tile + updates grid
	hide( overlapAll )	Fade-out animation.  Does not remove this movieClip.
		
		
finished-puzzle movieClips: 
	is_puzzle						Boolean flag used to indicate that this as a finished-puzzle
	id									String containing this piece's unique identifier consisting of:  puzzleIndex_pieceIndex		ex: "0"
	file								String containing the path to the image file for how this puzzle-piece looks
	image_mc						MovieClip displaying this piece's image
	clickArea						MovieClip representing the clickable/draggable hit-rectangle of this piece
	snapToTile()				Function that moves this piece to the specified tile + updates grid
	hide( overlapAll )	Fade-out animation.  Does not remove this movieClip.
*/