Level — ICE 0.1 documentation

### Navigation

- next
- previous |
- ICE 0.1 documentation »

# Level

ICE levels are YAML files specifying what entities are spawned when, background effects, and so on. A level consists of any number of wave definitions and a level script. A wave definition describes a group of entities that are spawned together. The level script determines when these waves appear, and other things such as background effects.

## Wave definition

A wave is just an entity that uses its Spawner component to spawn entities. A wave definition starts by a “header” in format `wave waveName:` where waveName is the name of the wave. The wave then defines a spawner component. As a wave is an entity, other components could be defined as well if needed.

The spawner component can spawn entities with a delay and override their components. The most commonly overridden components are the physics component to set position of the spawned entity, and dumbscript component to set entity behavior. Other components can be overridden as well, e.g. weapons, health and so on. For detauls, see Spawner component documentation.

Example:

    wave turtlePawn:
      spawner:
        - entity: ships/turtle.yaml
          components:
            physics:
                position: [380, 0]
            dumbScript: dumbscripts/pawnLeft.yaml
        - entity: ships/turtle.yaml
          components:
            physics:
                position: [420, 0]
            dumbScript: dumbscripts/pawnRight.yaml

This wave is called `turtlePawn`. It will spawn two `ships/turtle.yaml` entities at positions `[380, 0]` and `[420, 0]`. The first entity will use the `dumbscripts/pawnLeft.yaml` dumbscript, the second `dumbscripts/pawnRight.yaml`.

## Level script

The level script is a YAML sequence of events that will occur during the course of the level. Like dumbscript, there is no contol flow; just a series of instructions to execute.

Example:

    level:
      !!pairs
      - effect text:
          text: 42
          font: default
          fontSize: 512
          color: rgbaFF000001
          time: 1.0
      - effect lines:
          minWidth: 0.225
          maxWidth: 0.9
          minLength: 3.0
          maxLength: 12.0
          verticalScrollingSpeed: 225.0
          linesPerPixel: 0.0015
          detailLevel: 6
          color: rgbaD0D0FF24
      - music: music/level/SomeMusicTrack.ogg
      - wait: 1.0
      - wave: turtlePawn
      - wait: 0.3
      - wave: turtlePawn
      - wait: 0.3
      - wave: turtlePawn
      - wait: 3
      - wave: turtlePawn
      - wait: 0.3
      - wave: turtlePawn
      - wait: 0.3
      - wave: turtlePawn
      - wait: 5
      - wave: [turtlePawn, [100.0,  0]]
      - wait: 0.3
      - wave: [turtlePawn, [200.0,  -20]]
      - wait: 0.3
      - wave: [turtlePawn, [300.0,  -40]]
      - wait: 3
      - wave: [turtlePawn, [-100.0,  0]]
      - wait: 0.3
      - wave: [turtlePawn, [-200.0,  -20]]
      - wait: 0.3
      - wave: [turtlePawn, [-300.0,  -40]]
      - wait: 4.0

This level starts with a barely visible `text` effect showing a large “42” in the center of the screen for one second. It also uses a `lines` effect which generates small scrolling lines, giving the impression of a starfield. At start, a music track from `music/level/SomeMusicTrack.ogg` starts to play.

1 second after the level starts, a `turtlePawn` wave (defined above) is spawned. More `turtlePawn` waves are spawned in 0.3 second intervals, with a 3 second pause between the first three and the other three.

This is followed by a 5 second pause. After the pause, more `turtlePawn` waves are spawned, but this time with offsets altering positions of the spawned units. (This actually changes the position of the wave entity, which would be `[0, 0]` otherwise, and as entities are spawned relative to their spawner by default, this changes their positions as well).

## Level script instructions

effect X | Display specified effect. The effect itself is a mapping describing of parameters of the effect. X can be either `text` (show text centered in the screen) or `lines` (generate random lines on the background, useful for a starfield effect). Effect parameters are further described in tables below.
wave | Launch a wave, spawning its units. This spawns the wave entity. This instruction can be in one of multiple formats. These are described further below.
wait | Wait for specified time in seconds. Float.
music | Start playing specified music track. File name of the track in the ICE virtual file system is specified. The track should be in the Ogg Vorbis format, no other format is guaranteed to work. String.
text | Display specified text for 3 seconds. String. This should not be used - it is deprecated and will be replaced.

## Wave instruction formats

Launch the `waveName` wave at `[0, 0]`:

    - wave: waveName

Launch the `waveName` wave at `[X, Y]`:

    - wave: [waveName [X, Y]]

Launch the `waveName` wave, overriding wave entity components. This allows to change components of the wave entity - for example giving it a visual component or allowing it to move while spawning:

    - wave:
        wave: waveName
        components:
          physics:
            position: [100, 300]

## Text effect tags

text | Text to display. This must be specified; there is no default. String.
font | Font to use (must be in a `fonts` subdirectory of a mod directory). `default` means the default font. String. Default: `default`.
fontSize | Size of the font. Int. Default: `28`.
color | Color of the text. RGB or RGBA color. Default: `rgbaFFFFFFFF`.
time | Time to show the text for in seconds. `0` means infinite. Float. Default: `0`

## Lines effect tags

lineDirection | Direction of generated lines. Allows to generate rotated lines (but still moving in vertical direction). Float. Default: `0.0` (`0deg`).
minWidth | Minimum width of a generated line. Float. Default: `1.0`
maxWidth | Maximum width of a generated line. Float. Default: `2.0`
minLength | Minimum length of a generated line. Float. Default: `1.0`
maxLength | Maximum length of a generated line. Float. Default: `10.0`
linesPerPixel | How many lines to generate per pixel by default. “Pixel” might not correspond to a pixel on screen - it is a square 1 unit wide and 1 unit tall where the screen is always 800x600 units, regardless of the actual resolution. Float. Default: `0.001`.
verticalScrollingSpeed | Speed of vertical line movement in units per second. (there is no horizontal movement). Float. Default: `250.0`.
detailLevel | Effect detail level. Lower values will result in smoother line movement but higher CPU/memory usage. `0` is “full” detail. Int. Default: `3`.
color | Color of the lines.
time | Time to show the effect for in seconds. `0` means infinite. Float. Default: `0`.

### Navigation

- next
- previous |
- ICE 0.1 documentation »