Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
114 lines (99 sloc) 13.5 KB
- Visuals, Images:
Image files are defined as local or remote URL's, and include any format supported by your browser.
Animations are obtained by using animated image files.
You must include them inside url() tags! Example: "url(http://foo.com/bar.png)", not "http://foo.com/bar.png".
You can also use special types of images here. Example: "linear-gradient(to right, red, green)" will create a gradient that's red and green from left to right.
- Visuals, Colors:
Colors are defined in hex format. Example: "#ff0000" is red.
Note: If an image has transparent areas, images (explained above) can be layered on top of this color.
- Visuals, Alpha:
Alpha is the transparency of an object, defined as a value between 0 and 1. Example: 0.5 is half transparent.
Note: This affects both images and colors (explained above).
- Visuals, Geometry:
The geometries of sprites and layers are defined in a string, each value separated by a space.
Format: "left top width height z-index"; The first two define the top-left corner, the second two define the size, the last defines the draw order.
The default is "0% 0% 100% 100% auto". You can exclude any property you don't wish to set. Example: "25% 75%" will only set the top-left corner.
The first four values can be defined in either pixels or percentages. Example: "50% 100px 150% 300px". The fifth value is an integer.
Note: If the z-index is negative, the image will scroll with the screen. Use this if you want a background layer to have a parallax effect!
- Sprites, constants and variables:
Worlds are dynamically modified by changing two different things: Sprites and variables. Actions modify sprites to change the looks of an element, and variables to change values that persist world data.
You can additionally define constants in your mods. Constants are basically read-only variables, which you can use to create shortcuts for special values.
Sprites are collections of layers for the HTML elements defined by mods, defined in the data_sprites object of the json file, which can be swapped in between those elements.
You will normally create and use your own variables, but the engine has a few special variables builtin. The following variables can be read or modified to obtain special effects:
"$gameover": When set to any value, the current game ends and its save cookie its deleted. Writeonly property, do not read this!
"$random": Returns a random number between 0 and 1. Readonly property, do not set this!
"$date_hours": The current hour. Readonly property, do not set this!
"$date_minutes": The current minute. Readonly property, do not set this!
"$date_seconds": The current second. Readonly property, do not set this!
"$time_hour": Returns the time in standard format. Readonly property, do not set this!
"$time_date": Returns the date in standard format. Readonly property, do not set this!
"$time_start": The time when the world was created. Readonly property, do not set this!
"$time_last": The time when the world was last opened. Readonly property, do not set this!
"$game_name": Game setting, safe to set. Specifies the name of the player. Note that this is not the same as the name of the world!
"$game_speed": Game setting, safe to set. This is the speed offset, represents overall difficulty.
"$info_browser_name": Returns the name of the browser. Readonly property, do not set this!
"$info_browser_codename": Returns the code name of the browser. Readonly property, do not set this!
"$info_browser_engine": Returns the engine name of the browser. Readonly property, do not set this!
"$info_browser_version": Returns the version of the browser. Readonly property, do not set this!
"$info_platform": Returns the name of the operating system the browser is running on. Readonly property, do not set this!
"$info_language": Returns the language the browser is using. Readonly property, do not set this!
"$info_online": Returns 1 when the browser is online, 0 otherwise. Readonly property, do not set this!
"$info_cookies": Returns 1 when cookies are enabled, 0 otherwise. Readonly property, do not set this!
Both sprites and variables are used by elements inside the "conditional" and "action" strings of actions, as explained further down. However there are a few fundamental differences between the two:
First of all, sprites must be addressed directly by their name, whereas variables are addressed by $ followed by their name. "foobar" refers to a sprite, "$foobar" refers to a variable.
Note that sprite values can only be read for sprites that were set by an element! If a mod initializes "foo: bar", "foo" will return null... but if an action sets "foo = bar", "foo" will return "bar".
Variables may be set to either a string or a number, but sprites must always be thought of as strings (even if they consist of numbers). You may preform arithmetics on variables, but never do it on sprites.
When referring to a sprite or variable, you'll get its value if it exist and the reference string if not. So if "$apples" is a variable set to 1, you'll get "1"... if it's not a variable, the string "$apples" is used.
Also keep in mind that sprites and constants are not persisted in save cookies, whereas variables are. If you refresh the page of a running game, all changes to sprites will be lost.
Lastly be mindful of how many variables you define! Browsers have cookie save limits; If there are too many variables or their names and values are too long, you might get a corrupt save.
Note: It's recommended that you define variables in lower case and constants in upper case. For instance, "$my_var" versus "$MY_CONST". If a variable and a constant have the same name, the variable will be read.
- Objects:
Data and mods are defined in json files. Those files are specified in the mods menu before the world is created. The following structure is used:
"data_sprites": The global data object for sprites. Sprite definitions:
"<sprite_name>": The name of this sprite array, by which it will be referenced. Layers definition:
"inherit": Object indicating the layer to inherit. When set, this layer gets the properties of the given layer from the given sprite... its own properties will then override those of the inherited layer. Does not stack. Property inheritance only goes one level deep, objects within objects will be fully overridden. If either the "sprite" or "layer" fields are arrays, a random entry will be chosen each time. Example: ""inherit":{ "sprite":"my_sprite", "layer":"1" }".
"geometries": Object of geometry strings for mods. The element of each mod will be given a random position from this list when the scene loads. Example: Defining "mods_mymod":["25% 25% 10% 10% 1"] will always give the object of mods_mymod this geometry.
"layer": Object which defines the visual information of this sprite. Layer definition:
"geometry": Optional geometry string. If not defined, the layer will cover the entire area of the sprite.
"color": The fill color of this layer.
"image": The image on this layer.
"gradient": The gradient image of the layer. This overrides the "color" and "image" parameters when used. Gradient definition:
"value": The position of the gradient, ranging between 0 and 1. You'll almost always want this to be the name of a numeric variable. When a variable is used, the sprite will also be refreshed whenever that variable changes.
"color1": The color of the full side of the bar.
"color2": The color of the empty side of the bar.
"direction": The direction of the gradient. Can be: "left", "right", "top", "bottom".
"alpha": The transparency of the layer between 0 and 1.
"shadow": Specifies the shadow that surrounds this element. Format: x-offset, y-offset, blur, thickness, color. Example: "0px 0px 0px 3px #ffffffff". May contain a comma separated list of multiple shadow definitions.
"shape": How round the corners are, in pixels or a percentage. Four values can be specified for each corner if desired. Example: "10px 0px 100% 0%".
"cursor": The image or cursor style used by the mouse pointer, as it hovers over this layer. Always have a backup cursor specified when using images, if you want none use "auto"! Example: "crosshair" or "url(foo/bar.png), auto". Note: Only images of certain sizes are supported... 32px is most compatible, 128px is the known maximum.
"audio": Object which defines the audio of this sprite. The audio is always triggered when the sprite appears. Audio definition:
"sound": The sound file. This can be an array, in which case a random sound will be chosen each time.
"volume": The volume of this sound, ranges between 0 and 1.
"distance": Amount by which the distance of this sound source affects its volume. Distance is calculated based on the z-index of the mod this audio is on (not the layer). A z-index smaller than 0 gradually decreases the volume, whereas a z-index greater than 0 gradually increases it. This exist so that mods with probabilistic positioning can have different volumes... see the "geometries" section.
"loop": If true, this sound will loop.
"id": Registered name of this sound. Any existing sound source with this id will be replaced by the sound defined here.
"text": Object which defines the text of this layer. Text definition:
"content": Text to appear inside the element. This can be an array, in which case a random text will be chosen each time. Words beginning with $ represent the variable with that name if one exists. If followed by another $ and a number, that number acts as a visual multiplier for numeric variables. Example: "$myvar" becomes "1" if myvar is 1, "$myvar$5" becomes "15" if myvar is 3. Note: This only works for variables without special characters in their name (only a-z, A-Z, 0-9, _).
"align": Alignment of the font inside the element. Valid values are: "left", "center", "right".
"shadow": Specifies the shadow that surrounds this text. Format: x-offset, y-offset, blur, color. Example: "0px 0px 1px #000000". May contain a comma separated list of multiple shadow definitions.
"size": Size of the text.
"weight": Thickness of the font. Example: "200", "400", "600", "800".
"family": Font family to be used. If a comma separated list is present, fonts are used in that order... if left empty, the default browser font is used. Example: "Times, serif".
"color": Color of the text.
"tooltip": Tooltip to appear when hovering the mouse cursor over the element. This can be an array, in which case a random text will be chosen each time. Supports variables as described in "text":"content".
"actions": Object containing actions that can be set for this layer. Note that actions are evaluated in order, so later ones will override earlier ones! Action definition:
"trigger": What event will cause this action to fire. Can be: click, hover_start, hover_end, load, interval.
"conditional": Only execute those actions if the conditionals are true. The string must contain a property or value, a comparison type, and another property or value... all three may be separated by logical operators. Example: "my_var >= 0.5" or "my_str == foo_bar". Valid comparison types: ==, !=, <, <=, >, >=. Valid logical operators: &&, ||. Note: OR takes priotiry over AND, so "a == 1 || b == 2 && c == 3" will be treated as "a == 1 || (b == 2 && c == 3)", parenthesis are otherwise not supported by conditional strings.
"delay": The action will be delayed by this many seconds. If the sprite resets, its delays will be replaced and the old ones dropped... make sure you give each delay time to execute before another event can change the triggering sprite!
"action": Actions to execute. The string must contain a property, an action, and another property or a value. Multiple actions may be separated by the ; operator (don't add spaces around it). Simple values represent sprites or strings, values starting with $ represent variables. Example: "$my_variable += 0.1" or "my_sprite = foo_bar". Valid action types: =, -=, +=, *=, /=. Note: If the action or value are null, this deletes the property.
"<mod_category>": The global data object for mods. Each mod will create an unique element in the scene. Mods definition:
"<mod_name>": The name of this mod, by which it will be referenced. Mod definition:
"sprite": Object which defines the sprites (defined in data_sprites) this mod uses. The name may be anything you wish to set, while the string must be the name of a sprite from data_sprites.
"constants": Object containing a list of constants. Each constant is defined as a name followed by a value.
"variables": Object containing a list of variables with rules. Variable definition:
"value": The initial value this variable will have when created. Can be either a number / string or the name of another variable, however the later will only work for variables defined above this one!
"value_min": The maximum value this variable may reach. You'll usually want this to be 0 (default). Only applies to numeric variables.
"value_max": The minimum value this variable may reach. You'll usually want this to be 1 (default). Only applies to numeric variables.
"per_second": The variable increases or decreases by this amount every second. Only applies to numeric variables.
"per_variable": The variables listed here increase or decrease this variable by the given amount, as follows: -this if the other variable is 0%, no effect if it's 50%, +this if it's 100%. Only use this for variables defined above it! Example: ""per_variable":{ "$myvar1":"0.01", "$myvar2":"-0.01" }". Only applies to numeric variables.
"label": If this is set, the variable will appear in the settings panel of the menu prior to starting your world, and its name will show up as this value. Use this if your variable is intended as a custom setting.