Gamion Format. Draft.

Gamion Format. Draft.

	Legend:
		gamion	- "game or collection-file"
		opt     - optional
		req     - required
		scode   - application-source-code
		def     - definition

 

	Gamion simplified definition

	Examples: scripting and deriving in gamion.

	Gamion format:

		envelope - opt
		mapsscript - opt
	

	envelope - "header script", definition for games, albums, or for both. Its format is jwon.
	mapsscript - Colorban-script or script in sok-format (External link).

	Without mapsscript, gamion can serve like add-on to core games and albums.
	Without envelope, gamion can be just a plain Colorban or Sokoban maps file.

	envelope can contain game-definitions, album-definitions, collection-seed, and credits.
		In plain words, this is a json-like-formatted-text wich opens up with the token /{ and has insertions of
		"here-document" fragments,
		single-line-comments,
		and single-line property assignments.

	Here it is how complex gamion can look:
			/{ 
					"games" :
					{ 
						// new game
						"my_game" : "sample"
						...
					},
					"albums" :
					{
						...
					},
					"collection" :
					{
						....
					}
			/}
			#######
			# @$. #	
			#######
	The part with /{ .... /} is a envelope. The rest is mapsscript.

	Syntax-sugar is available, see first example at Game Craft.


	M a p s s c r i p t    f o r m a t

		MAP_LOOKUP - opt
			colorban directives - opt
			sokoban-header      - opt
				raw-comments    - opt
				macros          - opt
				plain text      - opt

		sokoban-map - opt
			map-title - opt (tricky: map starts from title, but map encounter is detected by map-board)
			sokoban-board-script - req
			postboard - opt
				title - opt
				author - opt 
				solution - opt
				solution - opt
				...
				plain text - opt
				...
		
		sokoban-map - opt
		...

		colorban-map - opt
			:::map... - req
				board - req
					sub-directives - opt; def: near //\\ dereferences map
					colorban-board-script - opt if sub-directives refer to other board
					:::board_end - req
				postboard - opt
					:::title - opt
					:::author - opt
					:::[any-credit-related-key] - opt, see list in /.\	AVAILABLE CREDIT KEYS
					(see directives in scode)
					:::playpath... - opt
						(see also: scode)
					...
					:::dress... - opt
						def: near //\\ COLLECTS DIRECTIVES FOR DRESS
					plain text
				:::map_end - opt only-if ::: map follows right away
		MAP_LOOKUP - opt; happens if :::map_end is not followed by :::map

		....



	B a s i c    d i r e c t i v e s

		Get an indea from source code section ///\\\ Digests :::-directive and runs short code.

		Map sugar: colorban board lines can be inserted like here:

			:::map
			-$-@-y-
			:::board_end

		Above map has no "#" symbol which stands for colorless wall. If your map has at least one line with
		"#", then each line of this map must have opening and closing wall, as in Sokoban map.

		Browse site's games, click on "About Map", "Edit Map Scripts", or "Collection Designer" buttons to learn from examples. 



	D e r e f e r e n c i n g

		Board in map can be omitted in case if map refers to map located in another album or collection.
		Directives in preboard-zone are: 

			:::akey
			:::collection_index
			:::map_index
			:::ckey
			:::mkey

		Get an indea from source code section //\\ dereferences

		:::context_akey

			//.\\ context_akey means ... 



	B o a r d

		In map-script, sequence of symbols describing units in one x,y-planar-location is called "cell".

		Row examples:

			sok-format compatible:			
			#-.$@#
			# . * + #

			Sokoban non-compatible:
			#   .h2     X #       #
			#   h2:3.x  X # .h1   #
			    h2:3.x  X y .h1   
				.h2:3   X y .h1   	

			Cells longer than one char must be separated with spacers.
			Symbols longer than 1-char require presense of "." which separates them.

			: - feature is not ready
				Number after :-character will be parsed to rank of unit h2.
				Rank is not yet implemented	in the application.
				The :-feature waits for this implementation.
			

		Crafter must know characters which are used in map script.
		(Map characters mapper is built by this code).
		


	D r e s s   . . 

		.. is Game's Skin and Meaning.

		Meaning: 	in the same Game in different Meanings, heros and walls may have different names and meaning.
				 	Different Meanings may have different stories and different text for rules.
		Skin:		the way how game looks and what images are used.

		Dress is defined in object "dresses" in album.

		Dress can be specified right in a map script. In this case it overrides properties of it's
		parent dress in album or adds an extra dress to dresses if no parent with the same name is in album.
		parent DRESS is referred by the name of the map's dress
			:::dress=DRESS
		or by directive 
			:::inherit_from=DRESS_X
				to make map's-DRESS inherit from DRESS_X
				see //.\\ inherits from default or from co-named parent:

		Get an indea from source code section //\\ COLLECTS DIRECTIVES FOR DRESS.

		
		Example for album designer:
			dresses: { default : { skin_key : 'dskin' }, special : { skin_key : 'nu_i_nu', ... }, ... }
			If nothing is set about dress in map, images taken from 
			def/skins/dskin for dress "default" and from def/skins/nu_i_nu for dress "special"

		For developer:
			default <-- base_game.dresses.default and 
			special <-- album.plgam.dresses.special <-- base_game.dresses.default
		


		Skins

			Directive

				:::skin=XXXX

			sets map's parser context to 'def/skins/XXXX'".
			Skins cannot be loaded from external urls, but images can.


			Images
			------

				If :::image=X=ZZZZ directive has a slash "/" inside ZZZZ,
				then skin context is ignored and ZZZZ is interpreted as path-directive. 


					:::image=f=blue_man2.png						...		result: image_url = gio.config.defpaths.SKINS_DEF_PATH + '/'+ ddww.common_skin_key + blue_man2.png  
					:::image=f=mypath/blue_man2.png					...		result: image_url = mypath/blue_man2.png
					:::image=f=//img/blue_man2.png					...		result: image_url = http://mysite.com/album/img/blue_man2.png
																					for external collection from http://mysite.com/album/collection.txt
																			apparently:
																			result: image_url = player_root_web_path/img/blue_man2.png
																					for bundled-to-player-collection
					:::image=f=http://here-we-are.com/tile.png		...		result: image_url = http://here-we-are.com/tile.png

					:::image=ground_x_3_1=ground_x_in_scene.png     ...     result: only ground_x with x,y = 3,1 is set to this picture

				Similar path conversions are true for
					:::back_image=transparent.png
					:::center_image=//transparent.png

				( Programmer can get an indea from section //\\	modifies image. )




	P l a y p a t h s

		:::playpath=MyTitle means playpath strings follow right after and named "MyTitle". 
		:::optpath=333.22 tells to metrics estimator that solution is optimal in sense of path, and
		           p,i = 333,22
		:::solpath=333.22 is the same as above but it is not know is solution optimal or not.

		:::playpath cannot happen after :::optpath or after :::solpath



	E x a m p l e s

		:::dress=flocks
		:::skip


		:::dress=night
		:::title=Night
		:::inherit_from=flocks
		:::skin=flocks
		:::chosen
		:::image=f=blue_man2.png
		:::back_image=transparent.png
		:::center_image=transparent.png

		:::multiplayer=N
			This is player's "sugar". N must be positive integer.
			If this directive is set, then it is assumed that there are two or more
			acting breeds in the map, and after each move, focus is set to next breed.
			This "multiplayer" feature is ignored if this directive is absent.


		Back to Readme Home
When JS finds this token, #@title@# , then JS will make this div visible.