Overview
#=#=#=#=#=

A genre file a simple ´´.js´´ file that defines a single variable named ´´Genre´´.
It is usually divided into the following sections:

´´´´´´
Genre={
	genre:"identifier",

	templates:[...],
	models:{...},

	designation:"text",
	description:"text"
	credits:{...},
	tags:[...],
	variants:[...],

	palette:{...},
	grid:{...},
	geometry:{...},
	
	symbols:{...},
	penbols:{...},
	markbols:{...},
	modes:{...},
	
	consfilters:{...}
	monofilters:{...}
	polyfilters:{...}
	glow:{...},

	explanations:{...}
	tests:{...}
}
´´´´´

If that seems a lot, don't worry, as most genres leave these sections to default values, and use [#templates] to define them. 



Let's start with the few sections that must be defined every time:


Signpost sections
#=#=#=#=#=#=#=#=#=#=#=#=#=#

genre
======
Every genre needs a unique identifier, and this is written after ´´genre:´´.
This identifier is read by the paper puzzle player (parameter ´´&G=´´ in the puzzlestring) so it knows which genre file to load (this file will always be named in the form ´´genre.js´´)

| :info: The genre identifier should be a kebab-cased string, that is: lowercase, hyphen-separated alphanumeric words.

Usually, a genre page will exist. If so, it will also be named ´´genre.html´´. Likewise, any genre thumbnails will also be named accordingly (e.g. ´´genre-512.png´´)


´´´´
genre:"akari-rgb"
´´´´


designation
===========
The genre title, as displayed everywhere:
- atop the Paper Puzzle Player, when the genre is loaded.
- as the title of the genre page, and of any links thereto.
- in link preview thumbnails
- etc...

´´´´
designation:"Akari (RGB)"
´´´´


description
===========
A concise explanation of the genre rules, as text. Much like the title, this appears:
- near the tof of the genre page, before infividual rule panels.
- as the bulk of the text in link preview thumbnails

´´´´
description:"Place some red, green, blue lights to illuminate every tile. Clues count orthogonally adjacent lights. Magenta, Cyan and Yellow tiles must be illuminated by the corresponding light combination."
´´´´

credits
===========

Information concerning genre authorship, publication, and implementation, condensed in an object frequently containing these subfields:

SUBFIELD	FORMAT		INTENDED USE
author 		name(s)		the author(s) of the ruleset (who usually also made the first puzzle)
date 		date		the date a full ruleset was first expressed (could be before or after the first puzzle)
url			url			the url where the rules were are shared, usually alongside the first puzzle(s)
publication	text		the name of the publication venue (e.g a Magazine, a website)
puburl		url			the url of the publication venue
porter 		name(s)		the author(s) fo the implementation
portdate	date		the date an implementation was deemed finished (even if subsequently updated)


The following subfields may appear occasionally:

SUBFIELD		FORMAT		INTENDED USE
transcriptor	name(s)		to credit someone who transcribed a significant amount of puzzles to the port
variant			name		the name of the original genre, of which the current genre can be considered a variant
preauthor		name(s)		(for variants only) the author of the original genre
inspiration		genres		(not for variants) list of genres that inspired the current genre
rules			text		custom text added after the rules (e.g. to give credit for their precise phrasing)
posdate			text		text added after the date, if some clarification is needed (e.g. due to uncertainty)
panels			text		to credit someone who made the rules panels
contributions	object		object mapping contributor names to small textual descriptions of each's particular contribution (i.e. for rulesets with signifficant additions by others)
altnames		names		list of alternate names, if any


´´´´
credits:{
	author:"Jubale and Jolson",
	date:"2023-10-03",
	porter:"Pedro",
	portdate:"2023-10-04",
	variant:"akari"
}
´´´´



tags
===========

Tags make a genre searchable, for instance in the [new] page.

Common tags:

TAG									ADDED IN GENRES ABOUT
[loop|new?search=loop]				drawing closed loop(s)
[stick|new?search=stick]			drawing straight lines
[path|new?search=path]				drawing non-branching paths
[tree|new?search=tree]				drawing branching paths
[territory|new?search=territory]	region division
[shading|new?search=shading]		shading individual tiles
[numeric|new?search=numeric]		numbers
[piece|new?search=piece]			placing symbols
[arrow|new?search=arrow]			arrows

Less common tags:
[polyomino|new?search=polyomino]	polyominos
[colour|new?search=colour]			colour mixing
[ice|new?search=ice]				ice tiles

Many other tags are available. Please search the [new] page and add as many as appropriate.

´´´´
tags:['colour','numbers','piece'],
´´´´

|:idea: if you notice a group of genres with something in common, not yet marked by a tag, please @@@ suggest a new tag! @@@

variants
===========

A simple list with all compatible variant identifiers.
Specifying these variants is recommended as it informs setters (for instance in the [new] page ) that those variants are available.

For more info on variants, see [variants].

´´´´
variants:['hex','crossing'],
´´´´



Linked sections
#=#=#=#=#=#=#=#=#=#=#

These sections are used to define other sections concisely, both [across genres|#template] and [within a genre|#models].
You can skip reading this until you understand all other sections.

template
=========
Templates are partial genre files that only define a very small, specific aspect of a genre, e.g. a single section, subsection or a single aspect.
Essentially, templates are modules to be reused across genres.

Whenever you're defining a genre section, always ask yourself:
 - does a template for this already exist in previous genres? 
 - and if not, should this be a template?


It's not uncommon for a genre to load +10 templates in the template section:

´´´´
template:[
	"template-geometry-square",
	"template-line-square",
	"template-line-normal",
	"template-inframe-solve-simple",
	"template-models-symbols-varied",
	"template-symbols-absent-x",
	"template-penbols-solve",
	"template-sketbols",
	"template-modes-placement",
	"template-palette-primary:black",
	"template-visuals-markbottom"
]
´´´´

This prevents having to write multiple sections from scratch.

template precedence
=-=-=-=-=-=-=-=-=-=-
The following order is always respected:
- The template loaded below always overwrites (any aspect common to) all templates above
- The genre file always overwrites (aspects common to) all templates

If a variants are added:
- variant files always overwrite (any aspect conflicting with) the base genre
- a later variant always overwrites (conflicting aspects with) all previous variants

|:warn: instead of making a big template that is overwritten here and there, split it into smaller templates and load only those you need.


models
=======
The models section lets you define small snippets to be used everywhere across the genre file.

´´´´
models:{
	"symbol-square":{
		path:"M 20 20 L 0 20 L 0 0 L 20 0 Z",
		viewBox:"0 0 20 20"
	},
	"symbol-target":{
		model:"symbol-square",
		scale:0.45,
		textColour:"black",
		colour:"black",
	}
}
´´´´

To load a model anywhere, just invoke the ´´model:´´ aspect. During preprocessing, model references are replaced by their concrete values.

So this concise snippet:
´´´´
symbols:{
	"red-target":{
		model:"symbol-target",
		colour:"red"
	}
}
´´´´

Would be expanded as:
´´´´
symbols:{
	"red-target":{
		path:"M 20 20 L 0 20 L 0 0 L 20 0 Z",
		viewBox:"0 0 20 20",
		scale:0.45,
		textColour:"black",
		colour:"red"
	}
}
´´´´

In the example above, notice how the colour ´´"red"´´ overwrites ´´"black"´´ .


models referencing models
=-=-=-=-=-=-=-=-=-=-
Models can reference other models in their definition; any conflicting aspects are overwritten.

model precedence
=-=-=-=-=-=-=-=-=-=-
Multiple models can be invoked at once (´´model:[...]´´), later models overwrite any conflicting aspects from earlier models.

|:warn: if an aspect is overwritten by successive models, consider removing it from those models and add it explicitly



Palette
#=#=#=#=#=#=

This section allows you to name colours. Defined colour names can be used everywhere in the genre file, including within the palette itself, as an indirect reference.

The left hand side contains the desired name, while the right-hand-side contains the colour in a compatible colour format. 

´´´´
palette:{
	"red":"rgb(255,0,0)",
	"green":"rgb(0,240,0)",
	"blue":"rgb(0,0,255)",
	"ruby":"red",
	"emerald":"green",
	"sapphire":"blue"
}
´´´´

All palettes are to be understood as overwriting the //default palette//, known by all genres. See the [palette] for more details.


Preset palettes
===============

Good-looking palettes can be loaded quickly using preset templates:
	- palette-primary-... lines and symbols
	- palette-secondary-... highlights
	- palette-neutral-... grid, frame, legend
	- palette-marker-... aux marks and sketch lines

Primary and Secondary
-=-=-=-=-=-=-=-=-=-=-=
For primary and secondary palettes, ´´...´´ can be replaced with a colour:
- black
- purple
- indigo
- blue-dark
- blue
- blue-light
- green-dark 
- green
- yellow
- orange
- red
- brown-dark
- brown

Neutral and Marker
-=-=-=-=-=-=-=-=-=-=-=
These can reference the primary or secondary palettes:
- ´´palette-neutral-primary´´: inherits from primary palette
- ´´palette-neutral-secondary´´: inherits from secondary palette
- ´´palette-marker-primary´´: inherits from primary palette
- ´´palette-marker-secondary´´: inherits from secondary palette


Grid and Geometry
#=#=#=#==#=#=

Grid
=======

The following  aspects of the grid can be styled:
 - internal gridlines
 - outer frame
 - grid tiles
 - grid dots
 - row/column legend

Different styles should apply to distinct situations:
- default (grid in solve mode)
- edit (grid in edit mode)
- win (grid when a puzzle is solved)


With templates
=-=-=-=-=-=-=-=-=
Most genres should pick a few common grid templates:

Common templates:
IDENTIFIER							EFFECT
template-inframe-solve-simple				a simple grid with thin solid lines
template-inframe-dash-normal				instead of solid, grid lines will have a dashed pattern 
template-inframe-none					remove the grid entirely
template-exframe-medium			set the frame thickness to medium
template-exframe-thick			set the frame thickness to thick
template-exframe-dash-space			instead of solid, frame lines will have a dashed pattern
template-exframe-only			do not draw the grid, only drawn the frame
template-exframe-none			remove the grid frame

Rarer templates:
IDENTIFIER							EFFECT
template-frames-light					makes the grid lines lighter
template-guide-circle					add intermediate dots to the grid (e.g. in [Myopia])
template-axis-simple			add simple row/column legends (e.g. in [Soulmates])
template-frames-hempuli			a specific grid characteristic of Hempuli genres
template-grid-hexo					a grid that displays better in the hexagonal geometry (e.g the dashes in edit mode will be perfect)


The colours can be specified via the palette:

COLOUR					DEFAULTS TO			APPLIES TO
grid					neutral-darkest		grid lines
frame					grid				frame
neutral-darkest			black				-
neutral-lightest		white				tiles
golden-light			...					grid and frame (winning)
golden-lightest			...					tiles (winning)


From scratch
=-=-=-=-=-=-=-=-=

The fully styled default grid looks like this:
´´´´
grid:{
	solve:{								//styles for the grid, when in solve mode
		lineColour:"grid",					//colour of grid lines
		lineWidth:1,						//width of grid lines
		dash:[],							//dash pattern of grid lines
		frame:{								//default frame style, around the board
			lineColour:"frame",				//colour of frame, if different
			lineWidth:4,					//width of the frame lines
			dash:[],						//dash pattern of the frame lines
			lineJoin:"miter",				//join style of the frame lines
		}
	},
	edit:{								//styles for the grid, when in edit mode
		lineColour:"grid",				//colour of grid lines
		lineWidth:2,						//line width of the editing grid
		dash:Dash(8,5),							//dash pattern of the editing grid
		lineJoin:"miter",					//join style
		frame:{
			lineColour:"frame",				//colour of frame lines
			lineWidth:3,					//width of the "editing" frame lines
			dash:[],						//dash pattern of the "editing" frame lines
			lineJoin:"miter"				//line join style of the "editing" frame lines
		}
	}
}
´´´´




Geometry
========

With templates
=-=-=-=-=-=-=-=-=
Most genres should pick a few common geometry templates:

The most important geometries are the following:
IDENTIFIER								EFFECT
template-geometry-square					sets the square grid (orthogonal lines)
template-geometry-diamond				sets the diamond grid - used in [Gravel]
template-geometry-hexo					sets the hexagonal grid (vertex-down)


To add more cells outside the grid, currently two additional templates are supported:

IDENTIFIER								EFFECT
template-geometry-exsymboled-LU			adds one row of cells up (U) and left (L), e.g. [Tetritory] 
template-geometry-exsymboled-RD			adds one row of cells down (D) and right (R), e.g. [Gerrymandering]


These templates specify what happens at the puzzle frame:
template-geometry-division				disallows drawing lines and aux marks at the frame, e.g. [Clones]
template-geometry-vertex				allows placing lines and aux marks at the frame e.g [Crosswall]


From scratch
=-=-=-=-=-=

Behaviour around or at the frame:

IDENTIFIER			TYPE		DEFAULT VALUE		EFFECT
markverged			boolean		true				whether placing aux marks at the grid frame is allowed
lineverged			boolean		true				whether drawing lines with some endpoint at the grid frame is allowed
linebiverged		boolean		true				whether drawing lines with both endpoints at the grid frame is allowed
exsymboled			boolean		false				whether any symbols can be drawn outside the grid e.g. [Hamiltonian Plumbers]
exlined				boolean		false				whether lines can be drawn outside the grid e.g. [Alcazar]

Miscellaneous:

IDENTIFIER			TYPE		DEFAULT VALUE		EFFECT
free				boolean		false				whether the lines can be drawn freely from any poin to any other e.g. [Tricky Tour]

Compasses:

IDENTIFIER		TYPE		EFFECT
tileCompass		compass		defines the geometry of a regular grid, by listing all immediately adjacent points from the origin (and growing from there)
shapeCompass	compass		specifies the shape of each grid tile, by listing all its vertices in relation to the tile's geometric centre
exCompass		compass		if specified, adds extra cells outside the grid, for the chosen orientations

| :info: for info about compasses, check the [compass] page

The property ´´lineCompass´´ will move into [#penbols]. It can be used to define which immediately adjacent points can be connected by lines


Defining Symbols, Marks and Lines
#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=

Symbols are defined in the [#Symbols] section, Lines in the [#Penbols] section, and aux marks in the [#Markbols] section.

To add numbers and letters (subtypes of symbols) additional sections [#numbers] and [#letters] can be defined.

Common properties to all:

property		TYPE										DEFAULT					EFFECT
letter			single-character string, case sensitive		(compulsory)			the letter is used to identify a symbol
shortcuts		list of shortcut strings					´´symbol.letter´´		a list of all shortcuts that trigger input mode for that symbol
designation		text										(symbol's name)			a textual name for the symbol. If ommited will be derived from the symbol name.
model			list of model strings						´´[]´´1x1				models to ihnerit properties from (see [#models])
layer			number										´´0´´					a symbol will be drawn atop any symbols in lower(-numbered) layers
compass			compass										´´geometry.compass´´	when dragging, which immediate points can be used
uncompass		compass										´´{}´´					when the symbol is added, symbols in immediately adhjacent points which adjacent points are also candidates for deletion
monochromo		style object								´´{}´´					style overrides for monochrome mode, e.g. in [Decoration Tree]



Placements are a list of all possible placements for a symbol, specified as vectors with origin at the tile centre.

VALUE									MEANING
(default)								[[0,0]]
´´"tile-vertex-mid"´´					a list of points matching the the tile vertex displacements, from the centre 
´´"tile-edge"´´							a list of points matching the the tile edge midpoints, from the centre
´´CompassDemiPlacements(compass)´´			Uses points from the given compass (this may change to a shorthand in the future)
´´"circular"´´							a list of points in a circumference around the tile centre. The number of points matches the number of symbols with this property assigned


Symbols
=======

Each symbol listed in the symbols is a named object containing properties and styles.

Symbol-specific properties:
PROPERTY		TYPE				DEFAULT VALUE						MEANING
slots			list of slots		´´["supraharvest","infraharvest"]´´	supraharvest means the symbol can be used in play mode, infraharvest means the symbol can be used as a clue (in edit mode) 			
txt				text				undefined							if specified, adds text to a symbol
tiled			boolean				false								whether a symbol should be shaped like the underlying tile
unwinned		boolean				false								whether a symbol should be hidden from the winning screen, e.g white squares in [Soulmates]
unexsymboled	boolean				false								whether a symbol can be placed outside the grid


Internal properties:
These are listed for completeness only and should not be used.

PROPERTY		TYPE				DEFAULT VALUE						MEANING
auxed			boolean				false								whether a symbol should appear alongside aux marks
masked			boolean				false								whether a symbol can be used to remove tiles

Undocumented yet: obstacled, explacements, encogroup, region, orientation, transform, rotagroup


´´´´
symbols:{
	"target-magenta":{
		letter:"M",
		txt:"BR",
		shortcuts:["M","R,B","B,R"],
		model:"symbol-target",
		colour:"magenta-light",
	},
	"target-yellow":{
		letter:"Y",
		txt:"RG",
		shortcuts:["Y","R,G","G,R"],
		model:"symbol-target",
		colour:"yellow-light",
	},
	"target-cyan":{
		letter:"C",
		txt:"GB",
		shortcuts:["C","G,B","B,G"],
		model:"symbol-target",
		colour:"cyan-light",
	},
}
´´´´


Symbol templates
=-=-=-=-=-

IDENTIFIER								ADDS
template-symbols-absent-x				the ability to remove board tiles with [[X]]
template-symbols-question-y				question marks (given)
template-symbols-shade-z				shaded tiles (solve)
template-symbols-shade-z-bordered		shaded tiles, with a thick border matching the grid e.g. in [Trizone]
template-symbols-sf						a start [[S]] and finish [[F]] symbol

//template-symbols-shade-x
//template-symbols-coloured-tiles
//template-symbols-colours


Markbols
=======

Markbols are much like symbols, but contain other specific properties.

Symbol-specific properties:
PROPERTY		TYPE			DEFAULT VALUE		MEANING
prelined		boolean			´´false´´			whether a mark is kept after a line is drawn on top
lined			boolean			´´false´´			whether lines are kept when this mark is added on top
polycompass		compass			´´{}´´				which adjacent points receive an equivalent mark when drawing (used in diagonal marks)

In any case, most often they can be added directly as templates.

Markbol templates
=-=-=-=-=-=-=-=-=-=-

IDENTIFIER									ADDS
template-markbols-alphabet					tile-centered letters, ordered alphabetically A-I
template-markbols-chess						6 chess pieces, displayed in a circle
template-markbols-contiguous-diamond		small lines on tile edges, connecting adjacent tiles, for region-division genres
template-markbols-vertex-d					vertex-centered diamond
template-markbols-vertex-o-lined			vertex-centered circle, tolerates lines on top
template-markbols-diagonal-x				two small crosses blocking a tile diagonal
template-markbols-diagonal-x-edge			two small crosses blocking a tile diagonal, for edge lines
template-markbols-diagonal-subhexa			'' for the hex grid
template-markbols-division					edges, used for region division, e.g [Limbs]
template-markbols-edge-o					edge-centered circle
template-markbols-edge-vh					edge-centered ticks 
template-markbols-edge-x					edge-centered crosses
template-markbols-knight					small circles blocking lines in all 8 knight directions
template-markbols-knight-vertex				'' vertex-centered
template-markbols-monomino					tile-centered monomino, for polyomino genres e.g. [Tetro Stack]]
template-markbols-o-parity-two				-
template-markbols-shade-parity				4 coloured tiles
template-markbols-shade-parity-two			2 coloured tiles
template-markbols-shaka						subdivision of the square tile into triangles
template-markbols-tile-d-diamond			tile-centered diamond
template-markbols-tile-o					tile-centered circle
template-markbols-tile-o-lined				tile-centered circle; tolerates lines on top
template-markbols-tile-s					tile-centered square
template-markbols-tile-s-lined				tile-centered square; tolerates lines on top
template-markbols-tile-x					tile-centered cross
template-markbols-tile-x-lined				tile-centered cross; tolerates lines on top
template-markbols-tile-y					tile-centered question mark


Penbols
=======

In addition to [styles], there are some penbol-specific properties:
PROPERTY		TYPE				DEFAULT VALUE						MEANING
slots			list of slots		´´["supraforest","infraforest"]´´	supraforest means the line can be used in play mode, infraforest means the line can be used as a given clue (in edit mode) 			
midplacments	placements			"tile-edge"							placement of line midepoints (for the predictive cursor)


Penbol templates
=-=-=-=-=-=-=-=-=-=-

IDENTIFIER						ADDS
template-penbols-given			given lines, tile-centered
template-penbols-given-edge		given lines on edges
template-penbols-solve			solve lines, tile centered
template-penbols-solve-edge		solve lines, on edges





Explanations and tests
#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=

Explanations
============

Explanations, a.k.a. "rule panels" are shown on a the top of every genre page just below the rules description.
They are essential for new players. These images depict key puzzle states, some correct (pass), some incorrect (fail). 
They are  on page load, and the pass/fail text is addd below, with a corresponding checkmark/cross.

and others that are merely descriptive (description).

´´´´´´´´´´´´´´
explanations:{
	"shine-all-tiles":{
		fail:"All tiles must be illuminated",
		pic:"W=4x4&LF=g0r3b8b1&L=G0z1R2(1)1z2(2)1z1B4z2B1",
	},
	"count-akaris":{
		pass:"Numbers count orthogonally adjacent light bulbs",
		pic:"W=6x6&LF=b1r3b2r5b2g8g5g2g5&L=(1)3(2)2(3)2(0)9(4)11C3",
	},
}
´´´´´´´´´´´´´´

| :info: puzzlestrings added as pass/fail in the explanations double as unit tests, so they need not be repeated in the unit tests section

Unit tests
==========

No genre implementation is complete without a solid set of unit tests. They ensure the genres remain be stable and flawless as the editor grows and changes.

Tests apply to puzzlestrings and can currently be of two types:
- **fail** : the puzzlestring represents a puzzle in incomplete or incorrect state (not solved) 
- **pass** : the puzzlestring represents a puzzle in the solved state 

A well-chosen fail test must fail due to:
- a *single violation* of a puzzle rule, or
- an interesting edge-case in a more complex rule

A well-chosen pass test can:
- represent an interesting edge case in a complex rule
- represent a correction to a fail test
- occasionally be a slightly larger, complex puzzle, where all rules would be used simultaneously

| :warn: Unit tests must be kept as small as possible, usually size 2x2, 3x3 or 4x4, and avoid repetition, so thousands of fail tests can run in a short time.

In total, a genre file usually contains between 5 and 20 unit tests. All use the format:´´"puzzlestring":"description"´´


´´´´´
tests:{
	'pass':{
		"W=2x2&LF=b2&L=z1B2":"minimal example",
		"W=2x2&LF=g0g3&L=z1G1":"similarly minimal example",
		"W=3x3&LF=g2r2b2&L=(0)0C8":"one obstacle and all tiles illuminated",
		"W=2x2&LF=r1&L=z2R1":"right color target",
		"W=3x3&LF=r0g5b2&L=R0z4G1B2":"akari directly on targets also illuminate them"
	},
	'fail':{
		"W=2x3&LF=r2w1&L=z4R1":"all unknown light bulbs must become known",
		"W=2x2&LF=r2r1&L=R0(1)1":"one akari lighting another",
		"W=2x2&LF=g2r1&L=G0(1)1":"one akari lighting another, of a different colour",
		"W=2x2&LF=g0g3&L=(1)1G1":"one adjacent akari to many",
		"W=2x2&LF=g0g3&L=(3)1G1":"one adjacent akari to few",
		"W=2x2&LF=r1&L=z2B1":"wrong color lighting target",
	}
}
´´´´´


Testing variants
=-=-=-=-=-=-=-=-

When a new variant is added, corresponding unit tests should be added to the base genre too.
These will be normal puzzlestrings that include the ´´&V=variant´´ parameter.


Visual unit tests
=-=-=-=-=-=-=-=-=

TBA



Highlighting rules
#=#=#=#=#=#=#=#=#=

TBA

## Changes

**2022-12-22** Added an explanation of palette templates.