Overview

 

Zooom allows you to create custom levels using a simple script language. Levels are stored as text files in the LEVEL subdirectory. The extension of level files is *.lvl. A level file consists of several lines of code, the syntax of which is described below. Programming your own level is easier than it may seem: Take a look at some of the levels provided with Zooom, perhaps copy some lines of code to your new levels and I guarantee that you will have your first custom level working in under five minutes.

 


Code Structure

 

A level file consists of two sections. In the general section, placed at the beginning of the code, you declare global properties like background image, music and plugins. In the second section, the timeline, you define which enemy ships will appear on the screen at what time during the level, and what behavior they will show.

The timeline, as used in the AT or OFFSET commands (see commands), is measured in frames. For example, AT 250 would mean at the point when 250 frames have been rendered since the start of the level. Zooom tries to achieve a framerate of 100 frames per second, so theoretically, a timeline difference of 100 should equal one second, but on slower machines, the framerate may go down and the timeline will be stretched, too.

Within the timeline, you have a first level, the ship definition, to your command that controlls what ships are thrown on the screen. After issuing a SHIP command, all following commands relate to the ship you've specified, until you issue another SHIP command.

Within a SHIP command, you may issue a WAYPOINT command. This tells the ship to add a new waypoint to its internal list of waypoints. All waypoint-related commands following a waypoint command relate to that waypoint, until another waypoint is declared for the current ship or another ship is declared.

When you test your levels, you can use CTRL + 9 at any time during the game to turn on level debug mode. This mode disables collission checking and displays the current level timeline position on the screen.

 

 

Command reference

 

Level commands are stated line by line, where lines are seperated with CR/LF, exactly what you get by pressing the ENTER key on your keyboard. It is possible to apply some formatting to level commands by pressing TAB several times at the beginning of a line. The according TAB characters will be ignored during interpretation. Some commands have one or more arguments. Arguments must immediately follow a command and have to be seperated by SPACE characters. 
 

 
BEGIN
 This command must be the first command line in every level. It tells Zooom that from this line on, interpretation should take place.
END
 This command must be the last one in every level file. It tells Zooom to stop interpretation and leave the level file.
BACKGROUND bmp_filename
 This command defines which background image to use for the level. The image file can reside in the Zooom root directory (the default background files are located there) or in the PLUGIN subdirectory. You only have to provide the filename as argument bmp_filename, extension and pathname will be located automatically. The bitmap will be scrolled down the viewport according to the level lenght in such a way that the viewport will always be filled by the background image. Therefore, background images usually are 1000 to 3000 pixels high. Their widht should always be 400 pixels, as this is the width of the viewport.
Length length
 This command defines the lenght of the level in timeline frames through the argument length. If not stopped by a ship (see STOP LEVEL command), each new frame rendered will increase the global frame counter and thus scroll the background. The level is considered as solved when the global framecounter reaches the standing defined by this command. If the computer Zooom is run on achieves full framerate, length / 100 equals level duration in seconds, eg. LENGTH 2500 would make for a level having duration of 25 seconds.
MUSIC mid_filename
 This command defines which background music  to use for the level. The music midi  file can reside in the Zooom root directory (the default music  files are located there) or in the PLUGIN subdirectory. You only have to provide the filename as argument mid_filename, extension and pathname will be located automatically. 
PLUGIN plugin_name
 This command declares that the level will be able to access all media and definitions provided in the plugin file specified by argument plugin_name. In this argument, you have to specify the name of a valid plugin definition file (extension .plg) that is located in the plugin subdirectory.
AT timeline_point
 Sets the current timeline position to the point specified with the timeline_point paramter. Valid values range from 0 to the level length specified using the LENGTH command.
OFFSET timeline_offset
 Sets the current timeline position by adding or subtracting a specific amount of time from the current position as defined by the last AT or OFFSET command. This command is usefull for grouping enemies together: Assume you want a diagonal row of enemies coming straight down on you ... the row would start with an AT command, but to offset the individual ships against each other, you would just issue and OFFSET command. If you then want to move the whole fleet in the timeline, you would just have to change the initial AT statement, as all the offsets would stay the same.
SHIP ship_name
 Starts a new ship at the current position in the timeline. The ship is created from the template whose name you provide through the ship_name parameter. All subsequent commands will relate to this ship, until you issue another ship command.
WAYPOINT horizontal/vertical position_percent
 Tells a ship where to enter the game, or where to next change its direction, speed and other behavioral properties. Every ship in the game must have at least one initial waypoint defined. 

The first waypoint tells the ship where to enter: HORIZONTAL means the ship will enter from top, at the horizontal position provided in the position_percent argument. Left equals 0%, right equals 100%. VERTICAL means that the ship will enter from the side, at the vertical position provided. Top equals 0%, bottom equals 100%. With VERTICAL, the direction command to the waypoint specifies if the ship enters from left or from right: With a direction larger than 180 degree, the ship will enter from the right, with one below 180 degree, it will enter from the left.

Any further waypoints will applie their settings to the ship when they are reached by the ship, in the order you've provided the waypoints. The horizontal and vertical positions now must be read as kind of "lines": For example, a waypoint at HORIZONTAL 50 means that the waypoint is considered reached as soon as the ship crosses the vertical middle line of the screen, while a VERTICAL 25 waypoint would be applied as soon as the ship enters the upper quarter of the screen.

If a ship hits no waypoint (no matter if you didn't specify one or if it is programmed badly, meaning that the following waypoints can never be reached due to direction of the ship), the ship will leave the screen sooner or later. If this happens, in other words, if the image of a ship is completely off the screen, the ship is automatically removed from the list of active ships.
DIRECTION degrees
 Tells a ship that at the current waypoint, it should turn to the direction provided through the degrees parameter. Degrees are measured with zero degrees meaning "pointing up", and are counted clockwise. So 0 means up, 90 means right, 180 means down and 270 means left.

A special form of this command replaces the direction argument by the word PLAYER. So, the DIRECTION PLAYER command tells the ship to change its direction in a way that it is coming directly towards the players current position.

SPEED pixelperframe
 Tells a ship that at the current waypoint, it should change its speed to the setting provided with argument pixelperframe. A value of above 10 for speed is quite fast, and may lead to slightly shaky graphical impressions, as the ship jumps over more than one pixel a rendering frame. Note: You can improve graphical impression by increasing speed in steps of 5: 5, 10, 15, 20. 
ATTACK attack_propability
 Tells a ship to fire its weapons with a propability of attack_propability % each time the weapons have been reloaded. Note: Even at the 100% setting, weapons will not fire continuously. Despite this fact, a setting of 50% is already considered very high.
STOP LEVEL
 Tells the timeline to stop advancing until in another waypoint of the same ship, a RESUME LEVEL command is issued, or the ship leaves the screen or is destroyed. Cewl option for endgame opponents, but also usefull to save background image space.
RESUME LEVEL
 Resumes advancing the timeline after a stop level command has been issued.
CIRCLE clockwise/counterclockwise radius
 Tells the ship to fly a circle having the radius provided through the argument radius, in the provided direction. After the circle has been flown, the ship will continue to fly in the direction provided by the DIRECTION command for the waypoint. The radius should range from 1 to 5, not more as is is an argument relative to the framesize of the ship and not measured in pixel or frames.
LOOP waypoint_number
 Tells the ship to regard the waypoint provided through waypoint_number as the next waypoint. The number starts with the initial waypoint having number 1. Usefull for, e.g., letting an endgame opponent continuously fly around before your nose.

 

Campaigns

 

To bring some levels together in a campaign that will appear when you select the campaign menu in Zooom, you have to provide a campaign file in the level subdirectory. A campagin file must have file extension .cpn and follows a similiar syntax as the level file: It starts with BEGIN, it ends with END and commands inbetween may be preceeded by TABs for formatting.

There are two major commands within a campagin file: The LIFE command, followed by the score at which another extralife should be rewarded, and the LEVEL command, which defines a level that will appear in the campagin. Lifes will be rewarded whenever your score reaches one of the defined marks. Note: Score standings must be entered in ascending ordern.  Levels will appear in the campaign in the order they appear in the campaign definition file.

Regarding score keeping: Don't mind the *.sco-files that appear in the level subdirectory; Zooom will automatically create them and keep them up to date.

 

 

Examples

 

BEGIN
   
   BACKGROUND space
   MUSIC music1
   LENGTH 4500

   AT 25

      SHIP default_blocker1

         WAYPOINT VERTICAL 20
         DIRECTION 90
         SPEED 15

      SHIP default_blocker1

         WAYPOINT VERTICAL 20
         DIRECTION 270
         SPEED 15

   AT 50

      SHIP default_blocker1

         WAYPOINT VERTICAL 30
         DIRECTION 90
         SPEED 15

      SHIP default_blocker1

         WAYPOINT VERTICAL 30
         DIRECTION 270
         SPEED 15

   AT 75

      SHIP default_blocker1

         WAYPOINT VERTICAL 40
         DIRECTION 90
         SPEED 15
 

      SHIP default_blocker1

         WAYPOINT VERTICAL 40
         DIRECTION 270
         SPEED 15


   AT 350

      SHIP default_interceptor1

         WAYPOINT HORIZONTAL 25
         DIRECTION 180
         SPEED 10
         STOP LEVEL

         WAYPOINT VERTICAL 50
         CIRCLE CLOCKWISE 2
         DIRECTION 180
         SPEED 10
         ATTACK 50 
         RESUME LEVEL


   AT 2200

      SHIP default_boss

         WAYPOINT HORIZONTAL 50
         DIRECTION 180
         SPEED 10
         ATTACK 50

         WAYPOINT VERTICAL 50
         DIRECTION 90
         SPEED 10
         STOP LEVEL
         ATTACK 50

         WAYPOINT HORIZONTAL 90
         DIRECTION 270
         ATTACK 50
        SPEED 10

         WAYPOINT HORIZONTAL 10
         DIRECTION 90
         ATTACK 50
         SPEED 10
         LOOP 2


END

 
BEGIN
   
  LIFE 100000
   LIFE 250000
   LIFE 500000
   LIFE 1000000
  

  
LEVEL default_space
   LEVEL default_orbit
   LEVEL default_surface

END

 

List of built-in ships and powerups

 

The following ships may be used in levels...

DEFAULT_BLOCKER1 (tiny, rotates, no weapon)
DEFAULT_BLOCKER2 (small, rotates, no weapon)
DEFAULT_BLOCKER3 (medium, rotates, laser straight down)
DEFAULT_GUNSHIP1 (large, animated at shot, fireball straight down)
DEFAULT_GUNSHIP2  (huge, animated at shot, twin cannon straight down)
DEFAULT_INTERCEPTOR1 (small, directed, cannon shot)
DEFAULT_INTERCEPTOR2 (large, directed, fireball shot)
DEFAULT_CAPITAL1 (medium, animated, one turret)
DEFAULT_CAPITAL2 (large, animated, two turrets)
DEFAULT_CAPITAL3 (huge, still, four turrets)
DEFAULT_BOSS (endgame opponent, animated)
DEFAULT_ROCK1 (small asteroid)
DEFAULT_ROCK2 (large asteroid)

And this are the codes for the powerups, which behave exactly like ships, except that you cannot easily tell them to attack the player ;-)

TWINMOUNT
TRIPPLEMOUNT
WEAPON
SHIELD
REPAIR
DRONE
LIFE