# Bird's-eye view of a DungeonScript file

A DungeonScript file is divided into 8 sections:

## Objects

Here's where your in-game objects are all declared. The simplest way is to give something a name and a color:

    Friend
    Blue

If you do this, the Friend object will be a blue square on the floor.

You can tell the object to render as a sprite, and specify a texture as a grid as follows:

    Friend
    sprite
    PINK YELLOW BLACK
    .222.
    .000.
    22122
    .222.
    .2.2.

Which gives you this wee fella:

The dots represent transparency, and the numbers 0..9 index the colours in the second line.

I'm getting slightly ahead of myself here, but I should mention the following convenience: instead of doing it in the legend section, you can specify a character that you can use to refer to the object when level editing just by putting it after its real name:

    Friend F
    sprite
    PINK WHITE BLACK
    .222.
    .000.
    22122
    .222.
    .2.2.

The available colour names are:

> - black
> - white
> - grey
> - darkgrey
> - lightgrey
> - gray
> - darkgray
> - lightgray
> - red
> - darkred
> - lightred
> - brown
> - darkbrown
> - lightbrown
> - orange
> - yellow
> - green
> - darkgreen
> - lightgreen
> - blue
> - lightblue
> - darkblue
> - purple
> - pink
> - transparent

You can use hex-codes instead of these names, if you prefer:

    Friend
    #FF5555 #FFFFFF #000000
    .222.
    .000.
    22122
    .222.
    .2.2.

### Textures

In PuzzleScript every object was either a solid color or a 5x5 texture. DungeonScript supports these options, but also loosens the restrictions a little.

DungeonScript textures can be any resolution, and can even be non-square. So this:

    Rainbows
    red orange yellow green blue purple
    012345
    543210

is fine, and looks like this:

Sometimes you need more than one texture for an object, in which case you simply list them one after the other with a & in between, like so:

    Friend
    red green blue darkred darkgreen darkblue
    ...
    345
    &
    012
    345
    &
    012
    ...

If you happen to miss a row or a column in a texture that's fine, DungeonScript will just make those pixels transparent. So this:

    FlyingCarpet
    red green blue darkred darkgreen darkblue
    .
    &
    0000000000
    0011111100
    0011221100
    0011111100
    0000000000
    &
    ...
    .....
    .

is the same as this:

    FlyingCarpet
    red green blue darkred darkgreen darkblue
    ..........
    ..........
    ..........
    ..........
    ..........
    &
    0000000000
    0011111100
    0011221100
    0011111100
    0000000000
    &
    ..........
    ..........
    ..........
    ..........
    ..........

If you're using a lot of blank textures - and with voxels you probably will - then that can save a lot of screen space and typing.

### Render Types

You've seen how, by default, objects draw on the floor. And you might also have noticed that we added the optional render type sprite after the object name to make the object stand up and look at you. Cool! Now let's examine some render types in more detail.

floor
  This is the default render type, applying the object's first texture to the floor. This is what you see when you don't specify a render type.
ceiling
  Like the floor, but above you, and not the default. If you don't draw a ceiling then you see through to the background color.
wall
  Our first vertical render type, this draws all four walls around the object using the object's first texture.
billboard
  This draws the first texture upright, facing in the same direction as the camera. This means the texture draws as a square on the screen. It can be useful for things that look a bit the same from all directions, but don't look directly at the player.
sprite
  Similar to a billboard, except instead of facing in the same direction as the camera this faces at the camera. This subtle distinction means you sometimes see perspective on the sprite. These are great for making characters look at the player.
sandwich
  A sandwich is a ceiling and a floor all in the one object. This saves having to mess around with multiple layers and overlapping objects when you want textures both above and below the player. The ceiling uses the first texture, and the floor uses the second texture if one is specified, or the first texture if there is only one.
voxel
  Aha! On to the fun stuff! Voxel objects draw each texture element as a block, with the top texture providing the uppermost blocks, the next texture providing the next layer, and so on all the way to the ground. These stretch all the way between the floor and the ceiling, so you'll often want to add a couple of blank textures to the top so the object doesn't bump its head.
motionvoxel
  A motionvoxel is a voxel that faces in the direction it's moving. This can make objects feel a little more alive.
facingvoxel
  A facingvoxel is a voxel with the facing logic of a sprite. It stares at you. All the time.
hud
  This draws onto the screen, not as part of the world but as a single texture stretched across the entire canvas. These could be used for fancy borders, heads up displays, or other user interface notifications.

### Motion

When objects move from one location to another they slide using linear interpolation, however you can add a bit more life to your game by using different tweening functions. These are specified after the render type, like so:

    Rainbows
    easeinout
    red orange yellow green blue purple
    012345
    543210

Here are all the tween functions:

linear
  Move in a straight line at a fixed speed. This is the default, and kinda bland. It can be good for smooth player motion if you don't like view bob.
easein
  Similar to linear, but starts slow and accelerates until it hits its target. Can be good for striking or chasing behaviour.
easeout
  The opposite of easein. This starts with a bang and slows smoothly to a halt. This can be good for something responding to a collision, or for aggressive player motion.
smoothstep
  Smoothly accelerates into and out of the motion, with no sudden stop or start at either end. Good for snakes and worms I guess? Maybe robots? Slightly creepy.
step
  The same as linear, except it also moves vertically in a simple parabola. If applied to the player camera it feels like taking a single step.
doublestep
  Like step, but with two parabolas. Feels a bit like taking two steps, I guess. Can also be good for small creatures skittering around with many small hops.
bound
  This adds a pitching rotation to the step tween, so is perfect for a bounding puppy.
roll
  Linear, but with a full rotation around the x axis. Ideal for rolling boulders.
throw
  Similar to step, but with a second smaller bounce before it comes to rest. I find it fun to throw things around using this.