## Animation Description Language

This is a text version of my drawing of same name. 2018-01-04 CuriousTorvald

Author's node: yet another non-JSON domain-specific language because why not?

## Objective

* Java .properties-compatible
* Case insensitive

## Example code

```
SPRITESHEET=sprites/test
EXTENSION=.tga.gz

ANIM_RUN=DELAY 0.15;ROW 2
ANIM_RUN_BODYPARTS=HEAD;UPPER_TORSO;LOWER_TORSO;ARM_FWD_LEFT;ARM_FWD_RIGHT;LEG_LEFT;LEG_RIGHT
ANIM_RUN_1=LEG_RIGHT 1,-1;LEG_LEFT -1,0
ANIM_RUN_2=ALL 0,-1;LEG_RIGHT 0,1;LEG_LEFT 0,-1
ANIM_RUN_3=LEG_RIGHT -1,0;LEG_LEFT 1,-1
ANIM_RUN_4=ALL 0,-1;LEG_RIGHT 0,-1;LEG_LEFT 0,1

ANIM_IDLE=DELAY 2;ROW 1
ANIM_IDLE_BODYPARTS=HEAD;UPPER_TORSO;LOWER_TORSO;ARM_REST_LEFT;ARM_REST_RIGHT;LEG_LEFT;LEG_RIGHT
ANIM_IDLE_1=
! ANIM_IDLE_1 will not make any transformation
ANIM_IDLE_2=UPPER_TORSO 0,-1

ANIM_CROUCH=DELAY 1;ROW 3
ANIM_CROUCH_BODYPARTS=HEAD;UPPER_TORSO;LOWER_TORSO;ARM_FWD_LEFT;ARM_FWD_RIGHT;LEG_CROUCH_LEFT;LEG_CROUCH_RIGHT
ANIM_CROUCH_1=
...
```

### In-detail

```
ANIM_RUN=DELAY 0.15;ROW 2
```

Each line defines one property. A property is a field-value pair. In this code, field is ```ANIM_RUN```, and the value is ```DELAY 0.15;ROW 2```

The values are further parsed using ```;``` (semicolon with NO spaces attached) as a separator.

```
In this example, ANIM_RUN contains two variables:

DELAY = 0.15
ROW = 2
```

A value of the field is consisted of zero or more variable-input pairs. Variable and the input are separated with one or more connected spaces.

#### Variables

Variables can have only one of the two types: ```float``` and ```ivec2```. Single integer value ('2' in the ROW) are regarded as a float.

Float and Ivec2 are determined by:

* Ivec2: inputs that are matched by the regex ```-?[0-9]+,-?[0-9]+``` (we call this "ivec2 regex")
* Float: inputs that are matched by the regex ```-?[0-9]+(\.[0-9]*)?```, but not even partially matched by the ivec2 regex.

Any argument to the body parts takes ivec2, to move the parts accordingly.

#### Just one exception: SPRITESHEET and EXTENSION

SPRITESHEET and EXTENSION property is not parsed as a property, it's just a single string like the original .properties

### Naming convention of properties

If a field is recognised as an animation (in this case ANIM_RUN), the assembler will look for the fields named like ANIM_RUN_1, ANIM_RUN_2, ... , ANIM_RUN_9, ANIM_RUN_10 and beyond.

### Naming convention of files

If the animation specifies a "body part" (in this example LEG_LEFT and LEG_RIGHT), the assembler will look for a file ```sprites/test_leg_left.tga.gz``` and ```sprites/test_leg_right.tga.gz``` respectively. Filenames are advised to be kept all lowercase.

### Reserved keywords

These values must exist so that the file can be parsed successfully.

#### Root

|Name|Type|Meaning|
|---|---|---|
|SPRITESHEET|properties: NAME_ONLY|Base file name of the images|
|EXTENSION|properties: NAME_ONLY|Extension of the base file|
|CONFIG|properties: 2 variables|Frame size and origin-x position, 0 being left|

#### Animation

Remember that 'variables' are contained within 'properties'

|Name|Type|Meaning|
|---|---|---|
|DELAY|variable: float|Delay between frames, in seconds|
|ROW|variable: float|which row the animation goes in the spritesheet|
|SKELETON|variable: string_pair|Which skeleton this animation uses|

#### Transforms

Things like ```LEG_RIGHT -1,0``` within ```ANIM_RUN_3``` are called 'Transform'

|Name|Type|Meaning|
|---|---|---|
|ALL|variable: ivec2|Shifts (translates) everything by set value|

### Notes

* All indices are one-based

## Operation

* Each line describes transformation
* Transformation are applied sequentially from left to right. In other words, their order matters. Be wary of the clipping that may occur! (really?)
* The Field is an identifier the game code -- sprite assembler -- recognises.
* The Field of animation's name is the name the game code looks for. Example: ```this.setAnim("ANIM_RUN")```
* Coord system is Y-Up, meaning Y=0 is the bottommost position.
