Characters are drawn in Adobe Illustrator and exported as one SVG per pose or frame. The file name says which character and which action it is; the names of the layers inside it say which part of the body each shape belongs to.
Also as a quickstart and a cheatsheet.
assets/characters/player/ the player
assets/characters/enemy/ every enemy, one flat folder
assets/characters/friendly/ planned: friendly characters (empty for now)
assets/characters/neutral/ planned: bystanders (empty for now)
support/ Illustrator source files (.ai), not committed
Keep the .ai sources in support/. That folder is git-ignored because detailed
art files grow quickly; support/source-player.ai and support/source-enemies.ai
are committed as examples. See scripts/README.md.
| File | Is |
|---|---|
<Name>.svg |
the default pose |
<Name>_<action>.svg |
a single pose for an action |
<Name>_<action>_<n>.svg |
frame n of an action |
<Name> is the character’s asset name: CrimeGuy, BadGirl, KingBruteBreaker.
The site that serves the game is case-sensitive, so a file name has to match the
name in the config letter for letter.
config/enemy-assets.jsonEnemy frames are wired in by configuration, not code. The file has four parts:
| Part | Is |
|---|---|
defaults |
the animations every enemy has, and how each plays |
enemies |
each character’s own animations, keyed by asset name, laid over the defaults |
attackTypeDefaults |
extras for an attack type, such as weaponAttack’s get-up |
wipEnemies |
characters whose art is still in progress: loaded with the defaults only |
An animation is a mode and a list of suffixes:
"BadGirl": {
"attackType": "bodyAttack",
"animations": {
"walk": { "mode": "loop", "suffixes": ["", "walk_1", "walk_2", "walk_1"] },
"attack": { "mode": "sequence", "suffixes": ["kick_0", "kick_1", "kick_2", "kick_1", "kick_0"] }
}
}
Each suffix names a file: "" is BadGirl.svg, "walk_1" is BadGirl_walk_1.svg.
| Animation | Default mode | Falls back to | Plays |
|---|---|---|---|
idle |
hold |
standing | |
walk |
loop |
moving | |
attack |
sequence |
idle |
a strike |
powerAttack |
sequence |
attack |
a stronger strike |
damage |
sequence |
idle |
taking a hit |
preDefeat |
hold |
damage |
the blow that finishes it |
defeat |
hold |
idle |
down for good (default file <Name>_defeat.svg) |
taunt |
sequence |
after getting back up | |
block |
sequence |
idle |
optional guard (block, block_hold) |
blockResist |
hold |
optional, the guard shuddering (block_resist) |
|
getUp |
sequence |
preDefeat |
weaponAttack enemies only |
An animation with no art falls back down that column, so a new character needs very little to start.
| Mode | Plays |
|---|---|
hold |
one pose; given a duration, plays through and holds the last |
loop |
cycles |
sequence |
plays once and holds the last frame |
yoyo |
out and back without repeating either end: five frames are 0 1 2 3 4 3 2 1 |
An unknown mode is treated as hold.
First found wins:
<Name>_<suffix>.svg."defeat": ["damage_2", "preDefeat", "defeat"] works whether preDefeat is one
pose or several frames.<Name>_<suffix>_0.svg, _1, … for as long as they exist
(up to 64). Dropping SassyGirl_defeat_0.svg and _1.svg into the folder turns
a one-frame defeat into two frames with no config change.Other per-character settings (attackTime, files, canGetUp, getUps,
anchorWeapon, apply<State>) are described where they are read, at the top of
js/sprites/enemies.js.
<Name>.svg, <Name>_walk_0.svg, … into assets/characters/enemy/."<Name>": { "animations": { ... } } under enemies in
config/enemy-assets.json (or list it in wipEnemies to start with the defaults).ENEMY_DEFS in js/entities/enemy.js, whose img is
<Name>. This is the one step that is code today.js/level/data.js, or a level design’s
spawn group "pool" (level-design.md). Enemies
without boss or mini join the default pool on their own.The player’s frames are listed by name in js/sprites/player.js, so new player
frames need a line there. What exists today:
| Action | Files |
|---|---|
| idle | Player_Ideal_1.svg to _4 |
| walk | Player_Walk_0.svg to _7 |
| walk to run | Player_Transition_0.svg to _2 |
| run | Player_Run_0.svg to _7, with Player_Run.svg as the fallback |
| attacks | Player_Punch_1, _2, Player_Kick_1, _2, Player_UpperCut, Player_JumpKick, Player_RunningKick |
| guard | Player_Block_0, _1, Player_Block_hold, Player_Block_resist |
| hurt and down | Player_Damage and its numbered frames, Player_PreDefeat and _0 to _7, Player_Defeat |
Reactions an enemy applies. An enemy’s config can carry, for example,
"applyDamage": "Electrocuted", and a blow from it then plays
Player_Damage_Electrocuted.svg, or the numbered run from
Player_Damage_Electrocuted_0.svg. These are found by name, with no code change.
Illustrator writes every layer, group and path name as the id of its SVG
element. Named parts are what let the game recolor a vest (see
Recoloring parts) and, later, swap a jacket:
| Level | Names | Example |
|---|---|---|
| frame group | the artboard’s action and frame | walk_0 |
| part | the body part | front-glove, back-shoe, Head, hair, left-vest |
| tone | <part>-highlight, -light, -mid, -dark, -shadow, and outline (or a strokes group) |
vest-light, vest-mid, vest-dark, vest-shadow in JumpingJunkie.svg; arm-light, arm-mid, arm-dark in Player_Block_0.svg |
| outfit piece | one group per swappable piece | jacket-a, hat |
Unnamed items export with no id. A name used twice in one file gets a number on
export (strokes, strokes-12), so the game reads a part by its place under its
parent and its base name.
scripts/mapLayers.jsx renames layers in bulk from a JSON layer map, and
scripts/mapSelectLayers.jsx selects what a map points at so it can be checked in
Illustrator first. See scripts/README.md.
The part and tone names above are the ones recoloring reads. The rest of the scheme is planned (it is being agreed): outfit pieces, elite enemies with their own stats, and player outfit and color select.
A level design can spawn an enemy with some parts of its art in other colors, without new art: JumpingJunkie with his gold vest in gray. The design names the parts and a palette for each (level-design.md):
{ "enemy": "JumpingJunkie", "render": { "left-vest": "gray", "right-vest": "gray" } }
Palettes are in config/palettes.json (described by
config/schema/palettes.schema.json): the tone names, lightest first, and a color
for each tone in each palette.
{
"tones": ["highlight", "light", "mid", "dark", "shadow"],
"palettes": {
"gray": { "highlight": "#e3e3e3", "light": "#c7c7c7", "mid": "#848484", "dark": "#545454", "shadow": "#050505" },
"dark-gray": { "highlight": "#8a8a8a", "light": "#6a6a6a", "mid": "#4e4e4e", "dark": "#383838", "shadow": "#050505" }
}
}
The gray ramp matches how light the gold it replaces looks, so the vest keeps its contrast with the shirt and the outline. The dark gray ramp is darker than the colors it replaces, with its tones further apart than theirs: SassyGirl’s pink dress shades by hue as much as by lightness, and gray has only lightness to shade with. A palette missing a tone uses the nearest tone it has.
A pool entry can bring several of an enemy and recolor only some of them:
{ "enemy": "SassyGirl", "count": 2, "re-render": 1, "render": { "dress": "dark-gray" } }
is one SassyGirl in dark gray and one as drawn (level-design.md).
Every frame of the enemy is recolored as it loads; the files are never changed. In each frame:
| Step | Rule |
|---|---|
| part | every layer named the part, or a numbered copy of it (left-vest-2) |
| side fallback | a frame with no left-vest but with a vest uses vest: left-, right-, front- and back- are dropped. JumpingJunkie’s defeat pose draws its vest as one group, and turns gray this way |
| shapes | every path, rect, polygon, polyline, circle and ellipse in the part, except inside an outline or strokes group, and except shapes with no fill |
| tone | the nearest layer at or above the shape, inside the part, named <tone> or <anything>-<tone>, by its name before Illustrator numbered it (vest-mid-4 is mid) |
| no tone name | the tone whose color is nearest the shape’s own in lightness |
| color | set on the shape itself, which wins over the .cls-N rule it was filled by. Those rules are shared between parts, so they are never edited |
So name the tones of a part you want recolored, and keep its outline in a
strokes or outline group. A frame without the part warns once in the console
(“<Name>_<action>.svg has no left-vest, so it stays as drawn”) and is drawn as
it is. The level design’s checks look for each part in the enemy’s base frame,
<Name>.svg, and suggest the nearest layer name.
Check it: SANDBOX TEST, step design-7-render: a gold JumpingJunkie, then a
gray-vested one, walk out of the warehouse door.
See every frame, still: on the title screen, pick DEBUG MODES, then
DEBUG RENDER. It opens config/debug/renders.html, which also opens on its own
from the same server as the game (http://localhost:8000/config/debug/renders.html;
the published demo serves it at the same path). Pick a SANDBOX TEST, and each character its
level design recolors gets a page: every frame of every animation, as drawn
beside recolored, with the file name under it. A frame with no layer for a part
says so (“keeps as drawn: left-vest”) and has an orange border, and the line at
the top lists those files. Left and Right change the character. The player has a
page too, as drawn, since nothing recolors the player yet. The address keeps the
test and page (renders.html?test=level-design&page=1), so a link opens the same
page. P, Escape or the pause button at the top right pause it with the game’s
pause menu: EXIT goes back to DEBUG MODES with DEBUG RENDER
highlighted.
Older sets break the <Name>_<action>_<n> pattern in three ways. The config lists
the real file names, so they work; new art should follow the pattern.
| Today | Pattern |
|---|---|
Ideal for idle: Player_Ideal_1, BadGirl_ideal_0 |
idle |
action case varies: Player_Walk, Player_PreDefeat against BadOne_walk, BadGirl_preDefeat |
one case, decided in the template work |
frames from _1 in some sets (BadGirl_walk_1, Player_Ideal_1) and _0 in others |
from _0 |
A manifest that reads assets/ and wires characters in from their file names
alone is planned for the template version of this repo.