# Bird's-eye view of a DungeonScript file

A DungeonScript file is divided into 8 sections:

## Prelude

Before any of the "official" sections are declared, you can give details about your project in this section, and also set some editor options.

    title 2D Whale World
    author Stephen Lavelle
    homepage www.increpare.com

    require_player_movement
    key_repeat_interval 0.12

Here are the possible options:

author Stephen Lavelle
  Your name goes here. This will appear in the title screen of the game.
color_palette mastersystem
  By default, when you use colour names, they are pulled from a variation of Arne's 16-Colour palette. However, there are other palettes to choose from:

  - 1 - mastersystem
  - 2 - gameboycolour
  - 3 - amiga
  - 4 - arnecolors
  - 5 - famicom
  - 6 - atari
  - 7 - pastel
  - 8 - ega
  - 9 - amstrad
  - 10 - proteus_mellow
  - 11 - proteus_rich
  - 12 - proteus_night
  - 13 - c64
  - 14 - whitingjp

  (you can also refer to them by their numerical index)

again_interval 0.1
  The amount of time it takes an 'again' event to trigger.
background_color blue
  Can accept a color name or hex code (in the form #412bbc). Controls the background color of title/message screens, and the fog color, as well as the background color of the website. Text_color is its sibling.
debug
  This outputs the compiled instructions whenever you build your file. For instance, the line

      [ > Player | Crate ] -> [ > Player | > Crate ]

  is compiled into four instructions, as the output from debug shows:

      Rule Assembly : (4 rules )
      ===========
      (52) UP [ up player | crate ] -> [ up player | up crate ]
      (52) DOWN [ down player | crate ] -> [ down player | down crate ]
      (52) LEFT [ left player | crate ] -> [ left player | left crate ]
      (52) RIGHT [ right player | crate ] -> [ right player | right crate ]
      ===========

  the number on the far left is the group number of the disassembled - based on the line-number of the rules. The compilation step removes all relative directions ( ^, v, <, and >), and replaces them with UP, DOWN, LEFT, and RIGHT.
flickscreen WxH
  Setting flickscreen divides each level into WxH grids, then limits the renderer so that the player can only see one at a time. If the player moves from one part of this grid to another, then the new area will become visible and the old area will vanish.
homepage www.mypage.com
  The homepage of the author. This doesn't appear directly in the game itself, but is included in the exported HTML build.
key_repeat_interval 0.1
  When you hold down a key, how long is the delay between repeated presses getting sent to the game (in seconds)?
noaction
  Hides the action key (X) instruction from the title screen, and does not respond when the player pressed it (outside of menus and cutscenes and the like).
norepeat_action
  For many games, you don't want holding action down to retrigger it - games where you're toggling a switch, say. For these games, set norepeat_action, and the action button will only respond to individual presses.
noundo
  Disables the undo key (Z)
norestart
  Disables the restart key (R)
realtime_interval
  The number indicates how long each realtime frame should be. In the above case, twice a second the game engine will tick, but with no input. Player input is processed as regular. See this documentation for more info on making realtime games.
require_player_movement
  This is a common requirement in games - if the player doesn't move, cancel the whole move. This is equivalent, where there's only one player character, to the following:

      [Player]->[Player Temp]
      late [ Player Temp ] -> CANCEL
      late [ Temp ] -> [ ]

run_rules_on_level_start
  For some games, you will want, before the player sees the level, for the rules to be applied once.
scanline
  Applies a scanline visual effect - only draws every other line
text_color blue
  Can accept a color name or hex code (in the form #412bbc). Controls the font color of title/message screens, as well as the font color in the website. Background_color is its sibling.
title My Amazing Puzzle Game
  The name of your game. Appears on the title screen.
throttle_movement
  For use in conjunction with realtime_interval - this stops you from moving crazy fast - repeated keypresses of the same movement direction will not increase your speed. This doesn't apply to the action button. If you can think of an example that requires action be throttled, just let me know and I'll try accommodate you.
verbose_logging
  As you play the game, spits out information about all rules applied as you play:

youtube 5MJLi5_dyn0
  If you write the youtube tag followed by the ID of a youtube video, it will play in the background. Exported builds using this, obviously enough, will no longer be fully self-contained, but some might like it :) You'll only hear the music in the exported or shared versions, not in the editor.
zoomscreen WxH
  Limits the renderer to a WxH section of the map around the player. This is similar to, and works in conjunction with, view_distance. However unlike view_distance this is a rectangular shape, does not affect fog, and simply toggles tiles on or off rather than clipping them to a precise camera-relative shape.

### Render Settings

view_distance
  How far the player can see, in tiles.
view_pitch
  Can be used to make the player look up or down. If the player is tall and solving puzzles on the ground it can help to set this low, eg -20 degrees. If the player is short and being chased by giant robots then a value higher than zero would make them look more threatening. By default the player view is horizontal, which is 0.
view_height
  What height the player views from. 0 is the floor, 1 is the ceiling, 0.5 is the default, and values outside 0..1 are valid and sometimes quite useful.
scale_height
  Scales the height of all objects by this value. Default is 1. Can be useful for creating tall environments without messing with view_height.
field_of_view
  The player's vertical field of view, in degrees. Larger values help the player see what's going on around them, but distort the picture a bit.
fog_power
  How sharply the fog tapers off toward the end of the view distance. Large values (eg 5) can create a moody atmosphere, whereas smaller values (eg 0.2) keep the world looking crisp and colorful.
interpolation_interval
  How long it takes to perform one logic step. If this isn't specified then DungeonScript looks at values like key_repeat_interval to try to find a sensible value.
gradient_top gradient_bottom gradient_middle
  Whenever DungeonScript draws something in the world it multiplies the thing's color by a vertical gradient, which starts at the floor and extends to the ceiling. This can be used for fun effects like simple fake ambient occlusion or global illumination, or just to make things look a bit moody.