The Developer's Handbook

Copyright Penguin Development Team. All rights reserved.

Introduction
About this document
The name says it all; The Developer's Handbook. Origins of this manual go as far as the very first code snippets of TAGAP itself, as rather than being user guide to editing, this was developer's journal about the technology and development progress. However, I realized quite soon that this thorough journal could be used, with few additions, as complete guide to the engine and to make lives of Modders a lot easier. Thus I polished it a bit and added few extra sections trying to translate my otherwise cryptic nonsense and here it is. But it's still The Developer's Handbook; If you're not going to make any levels or game modifications for TAGAP, you can quit reading now. If you dare to continue, I sincerely hope you find this documentation at least remotely useful during your quest for fun gameplay.

File types
While many modern games are made of dozens of formats, we kept TAGAP as simple and clearly oriented as possible to ease working on it. In case you lack some software to work on the specified formats, we have listed most most freeware tools used to create TAGAP ( see: Appendix D: Essential Software).

TAGAP_Script
TAGAP_Script is simple external scripting system created for TAGAP Engine. Everything from system configurations and entity scripts to levels and even cut-scenes are made of this language. The extensions vary so you can right away see what they are used for; Level files are .map, configurations .cfg and scripts simply .txt. They are all simple ASCII text, so any Notepad-styled program works fine for scripting, while for making levels TAGAP features built-in level editor. Usage of TAGAP_Script is explained more in section Basics of Scripting and you can find complete list of TAGAP_Script commands from the Appendices section (see: Appendix B: TAGAP_Script Syntax).

Graphics
All TAGAP graphics are in Targa TGA format (.tga), with either 24bit (solid) or 32bit (with transparency) colors. Note that OpenGL needs textures and some effects to have power of two dimensions (i.e. 16, 32, 64, 128, 256...), but there isn't such restriction with sprites, particles etc. TAGAP supports RLE compression and usage of it is strongly recommended; The files are remarkably smaller and there is no image data loss.

Audio
TAGAP Engine uses 8 and 16 bit samples of 22050 Hz, ambient and cinematic stereo streams of 22050 Hz and streamed music of 16 bits and 44100 Hz. Samples should be mono as the engine handles all the stereo panning according to sound source, but global streams (like music and ambients) can (and should) be stereo. Preferred audio format is OGG Vorbis codec (.ogg) of any compression rate. Windows Wave (.wav) is also supported, but as it results very large files it's recommended to use Vorbis instead in your distributions. You can add loops into music files via id-tags. Tag START defines where the loop starts and END defines the endpoint, both in milliseconds. Start of the file is 0 and end of the file is sound file length in milliseconds minus one milliseconds (i. e. end of 1.5 second sound is 1499, not 1500).

[ 2 / 37 ]

Audio of TAGAP_Engine is powered by magnificent FMOD Ex Sound Engine from Firelight Technologies, used under their freeware terms (for more info visit official FMOD site at http://www.fmod.org).

General editing guidelines

TAGAP game modifications fall into two categories; Extra levels and Mods. To keep things as userfriendly as possible, it would be appreciated that you won't do anything in between. Levels should be strictly that levels. I know many of level makers would love to add new textures, but if you do, make it a Mod instead. If every level author out there just slaps their textures into game's main texture folder, players soon end up with TAGAP loading 200 Mb pile textures only one or two levels use. When creating Mods, you can do whatever you wish, just don't alter the files in TAGAP data folder; If you want Pablo to have a Hello Kitty tattoo on his belly, don't add it to the original sprite, but make a duplicate of it into your Mod-folder and edit that duplicate. This way the original game never gets broken and users can easily add and remove Mods. TAGAP itself can be run with relatively low amounts of memory, at least when compared to other games of today. That isn't, however, an engine limitation. If you want to make a Mod with superhyper-high-resolution content, it's all possible, but given TAGAP's low-end roots it would be appreciated that such case is clearly stated in Mod's documentation.

[ 3 / 37 ]

Creating Levels
Linedefs
1. Selected linedef appears as bright, thick line with arrows showing the facing. 2. Linedef index. 3. Selects the type of the linedef. 4. Nudge linedef around by one pixel. 5. Coordinates of the line's starting point. 6. Coordinates of the line's end point. 7. Length and vector components of the linedef as both pixels and grid units.

Linedefs, short for line definitions, represent the basic physical world; Vertical linedefs act as floor or ceiling, while vertical linedefs are walls. The facing, shown as arrows, tells from which direction the line is blocking. In example horizontal line defined Floor stops movement from above and as vertical it will block anything attempting to pass it from left. Lines are defined in Geometry mode and it couldn't be simpler. Just point at the starting point and hit [Space], then point at the end point and hit [Space] again. Once the line is defined you can drag it around as a whole by clicking it and moving mouse, or you can move it's points independently. Setting the line facing is important and can be done with selector or by pressing [C]. In addition to Floor and Ceiling, there's M-Floor and M-Ceiling; Those work physically the same, but act as metal when shot. Also, in game M-Floor appears as thinner metal plate floor (i. e. top of a transport crate).

Entities
1. Selected entity is bright and has visible bounding box. 2. Preview and description of selected entity (not all entities are available for preview). 3. Green dots are game characters. 4. Turquoise dots are items. 5. Miscellaneous objects appear as white dots. 6. Player start point appears as yellow dot. 7. Name of current entity (click to change the entity) 8. Changes the facing and/or starting angle. 9. Entities can start as active or inactive. 10. Nudge entity around by one pixel.

Entities represent most characters and objects in the game and range from player character and enemies to items and decoration. You can also select and edit properties of multiple entities at the same time. To add an entity, hit the either [E] (for actor entities), [I] for items or [D] for miscellaneous objects and decoration. The entity appears as red undefined entity at first, but you can select the right from the entity list. The player start point is relocated with [Insert]. You can also copy the currently selected entity by pressing [G]. You can have one entity for each three entity classes copied, use [E], [I] or [D] to paste. Entities can start the game either as active or inactive. Inactive entities require a trigger impulse to be awaken. Solid entity dots represent active entities and hollow dots are the inactive ones.

[ 4 / 37 ]

Triggers
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. Selected trigger appears as bright and bold. Functional triggers are purple. Decorative triggers are green. Sound emitters are turquoise. Exit trigger appears yellow. Water areas are shown blue. Name of the trigger and it's index number (click to change the trigger type) Coordinates of the trigger's upper left corner. Coordinates of trigger's lower right corner. Width and height of trigger in pixels. Normalizes trigger field dimensions to defaults. Nudge trigger around by one pixel. Each trigger style has it's own, unique set of options to modify their attributes.

Triggers form the functional core of TAGAP. Their purpose varies from simply appearing as decoration to triggering complex scripted events. In this chapter we talk about the basics of handling trigger fields, for thorough explanation of all trigger types, see Using Triggers. For TAGAP_Script syntax of triggers see: TRIGGER. All trigger fields are rectangles, so to define one you need to give it two points, just like with linedefs, only this time press [T] to add corners. Also like linedefs, triggers can be dragged around as whole or resized by dragging the corners. Some triggers, i.e. trigger or terminal, will require a target link. To define one for currently selected trigger, simply point the desired entity or area inside desired trigger and press [L]. Not all triggers can be linked, though. Also note that overlapping linkable triggers may require you to temporarily move the other one away. Most link-using triggers can be linked to multitaps; If so, there is Select multitap option available. Note that triggers not yet linked to anything will appear red.

Multitaps
1. 2. 3. 4. 5. 6. 7. Number of links in current multitap. Multitap index and selection. Adds a new, empty multitap. Deletes current multitap. List of linked objects with their indexes. Removes link from multitap. When selecting multitap for a trigger, the list shows multitap index followed by it's link quantity.

Multitaps, named after the retro console accessory of the same function, allow you to connect multiple objects into one trigger. Each multitap can have up to eight links and as each linked object may also be linked to multitap, you practically add unlimited events for one trigger. To bring up multitap editor, press [M] while in Geometry mode. To add a new multitap, click Add or browse through available multitaps to select previously defined one hold shift to leap faster through the inventory. Linking objects to multitap works just like with triggers; Point the entity or trigger you want to link and press [L]. If there are overlapping trigger fields you may have to link them both first and remove the incorrect one afterwards with DEL button. Triggers that can be linked to multitaps will have Select multitap option in their settings.

[ 5 / 37 ]

Textures
1. White border outlines the selected polygon. 2. Zoom window helps texture placement. 3. Name of current polygon's texture (click to bring up the texture list) 4. Rendering order; Larger the index, more front it is. 5. Moves to the back of the rendering list. 6. Moves to the front of the rendering list. 7. Polygon point used as texture offset. 8. Toggles texture shading on/off. 9. Nudge polygon around by one pixel. 10. Information on all the polygon's points (corners).

Texture polygons are the basic graphical building elements. The shapes can be anything from a triangle to hexagon and hold any of the texture images found in the game's texture folder. Drawing shapes is simple; Just point with mouse and press [Space] to start polygon and hit [Space] again to add a polygon point. To close polygon either hit [Enter] or point at the first point and press [Space]. All polygons can naturally be dragged around as a whole or by individual points. When creating large levels you'll really start to appreciate the quick tools. First is rectangle tool, with which you can define rectangular polygons just by defining two corners (press [T] or [R] two times). All shapes can also be copied and pasted ([G] gets the the current polygon and [P] pastes) and flipped horizontally ([H]) or vertically ([V]). You can also get the current polygon's texture ([D]) and fill some other shape with it ([D]). To change the order of polygons faster than with the selector, hold [Shift] and press [PgUp] or [PgDown]. One of the most important things to observe is usage of shaded textures; Shaded ones should be used as for things in background, while bright ones should represent either the foreground or things of importance. This gives the scenery certain illusion of depth. Also note that overdose effect uses these values to pick the colors, so not paying attention to balance of things will definitely look awkward. You can check the overdose view in editor by holding [Ctrl]. There's one special texture called (fade); Like the name says, it's used to fade scenery from bright to black or just to dimmed. Easiest way to control fading is to draw a rectangle by starting with the line representing the side that will be bright, completing the polygon and setting texture offset to 2 (press [2]). Shaded fade is rendered as shade instead of solid gradient and is ideal for making shadows to add illusion of dimensions.

Setting up properties
In Properties mode you can edit various global attributes that define how the level looks, sounds and above all, plays. Always remember that many of these options serve as start-up details and can be manipulated on the fly during play. Basically the main window is split into three sections. At the very top are the obligatory basics; Title of the level shown in the beginning (use Untitled for no title), level filename, filename of the next level, sequence to load between the levels and the filename of the music to play. You don't need to type them in, use Browse buttons to bring up lists of available files. Next up are the three first image layers. These are the ones used as parallax backgrounds and screen monitors (see: screen) unless they are disabled from them. First is image layer index (which is referred to by triggers like layer) followed by the image filename (in folder data/art/layers/). Below are the options to manipulate how image will appear. Scroll defines how well parallax image follows movement of the view. Offset is pixel interval between the image and the top of the view. The two move values give the image constant scroll on x and/or y axis. Finally theres additional rendering flag; Normal means it's handled as standard parallax, Gloom

[ 6 / 37 ]

makes that layer emit light when seen through windows, Fading fades the image from solid to completely transparent and Disabled prevents the layer from being rendered to parallaxes or screens. Only the three first image layers can have these values, the rest will always be Disabled. Simply click More layers... to add and edit the rest of the image layers. Next section has options to edit level setting and gameplay. First button defines background image rendering method, indicating either full parallax, or as interior background rendered only when seen through windows and doors. Scheme defines the default level theme used at level start (see: THEME_START). Below these are the cannon fodder settings. First selects the default cannon fodder, next is starting spawning interval and the direction of spawning. Enemies can be set to spawn from sides (by default), fall from sky or from all around the player. At the bottom of the main window there are two editor tools. First one centers the level to according to the most far left linedef and makes level dimensions to start from the x coordinate 0. This comes very handy while creating level data for sequences, as in them view is centered to point x400 y300, making x0 the left edge of the screen. The other option, start map from scratch, does exactly that; Wipes all level data from memory allowing you start a new map from the beginning. The bottom window can be set to view either the contents of default cannon fodder or the level statistic. It's always good to keep checking the stats so you don't find yourself surprisingly running out level size. There's plenty of room and the levels can be quite darn huge, don't worry about that.

[ 7 / 37 ]

Using Triggers
Now you know how to create and modify triggers, but what are they for? Each type of trigger field has it's own specific purpose and in this section you'll find introductions to them all. Under the description is trigger's 'on use' function thats what the trigger does when it is fired by another trigger or a multitap.
always description: Works just like field, only this one isnt turned inactive after being used. If you want some object or multitap to be fired multiple times without need of adding restore for each toggle, use always. on use: breakaway description: Works as static texture block that can be solid or non-solid. on use: brick description: Solid or non-solid moving block that can be set to use either a texture or an image layer. If texture has damage texture defined (see: TEXDAMAGE), it will be used instead after the first toggle. By default brick will move and sound like elevator, but if it stops to floor height when moving down, it will fall faster and shakes the screen on impact with floor. Texture brick can also be set to look like plain texture, metal plated block or fully detailed floor block; The types of the brick linedefs will be automatically set accordingly. The moving radius is shown in editor by thin line drawn from the bottom of the brick. It will move to the other end of the line when triggered, and back when triggered again. on use: clock description: Adds a clock to the level. It takes its time from system clock, so it should be on time when the level starts. However, cause time in TAGAP isnt a constant, time shown will ultimately be incorrect. on use: counter description: Counter monitor displaying numeric value, which can be either time counting down or index number counting up. on use: delay description: Like field, but fires the target after a defined time. The delay time is given in milliseconds. More complex scripted events always requires use of delayed events, so mastering use of these is a must. on use: door description: Door can be set to slide either up (default) or down when opened. If there are two doors, one moving up and one moving down, with their ends connected, it will appear as large doubleTriggers its target, turns inactive until its restored (see: restore). Add or subtract one from the counter value. Activates and starts to move to its other position. Texture block explodes with rubble flying around. Triggers its target, stays active.

[ 8 / 37 ]

door door. on use: doorstate description: State light can be linked to door, platform or brick. When linked object is opened, light is green, otherwise its red. If no link is defined, doorstate will remain red all the time. You can also set doorstate alignment, so it will be rendered on left or right, connecting either ceiling or floor. on use: elevator description: Guess what; Its an elevator! It can start in top or bottom position and be set to make a sound or move silently. Silent elevator also wont have elevator tracks automatically set on wall, so if use that if you want to create custom elevators. Normally elevators can be activated by pressing [Use] while standing on them, but if its target of some other trigger expect always it cant be activated that way. on use: envdamage description: A decorative block of texture that will break when damaged or hit by a ricochet. When damaged, the texture will change to damage texture (see: TEXDAMAGE) or if no damage texture is defined, the block will get crack texture overlay (see: Editing variables). You can set both texture dimming and block material from the editor. on use: exit description: End of a level area. Exit can be invisible field that activates when entered or triggered, or a door. When door opens, it can be set to show either textures behind it or background layers. Like window, depending on current level theme, open exterior door will result audible ambient sounds (like thunder or falling rain). By default the exit use ending sequence and following level as defined in properties (see: Setting up properties) with string NULL, but you can define some other sequence to be loaded as well, i. e. if you want to create exit leading to a secret level or something like that. Like many fields, exit can start either active or inactive. on use: fan description: Fan is standard rotating device you can control through various options like spinning speed and sprite frame. Amount of possible devices is defined simply by frames in fan sprite (art/sprites/world/fan_*), in TAGAP there are two possible devices, standard ventilation fan and small gear. Frame 0 works always as standard fan, emitting fan loop sound and spawning bubbles and smoke puffs if its in water or inside gas area. Fan can start on or off. on use: field description: Standard all-round triggering field can be activated either by other trigger or by playing stepping into the field area. Field can also be set to start inactive, requiring restoration ( see: restore) before it will fire. Toggles fan on/off. Either unlocks the exit door or activates exit. Breaks the block. Activates and starts to move to its other position. Opens or closes the door.

[ 9 / 37 ]

field on use: fishtank description: Clone tank with an entity floating inside. Clone tanks can be set to either make the entity break free or to kill the entity inside. By default fishtanks emit bubbling sound, but you can turn it off if you have multiple tanks turning game into cacophony. on use: focus description: Focus is used to create in-game cinematics where view is focused on something else than player and actual gameplay pauses. View is centered to the origin of trigger field for defined period of milliseconds. on use: fodder description: Changes cannon fodder to another (see: CANNONFODDER). Youll see a preview of that fodder, so the right one is easy to pick. Use trigger tempo to change fodder spawning interval. This trigger can be fired unlimited times. on use: forbid description: Forbids area from player access, cannon fodder spawning, or both. Very necessary, especially so when player has flying movement and can go beyond all level bounds. on use: forcewall description: Energy force field blocks all fire and blocks movement. Force walls can be either vertical or horizontal, which is defined by the field dimensions. They can also start active or inactive. on use: gas description: Area of lethal gas will damage everything organic. on use: guide description: Most dynamic way of rendering an entity to the background, guide is used to add lamps, monitors, guide arrows and other similar decoration to the levels. Guides can be toggled on/ off and destroyed. If used entity has corpse defined ( see: CORPSE) it will be used as broken entity. on use: hologram description: Something between guide and envdamage, with hologram you can render entities either as full entities that break like envdamage, or as holographic representations. Hologram entities are a lot more simplistic and you have less control over them, but they work great for decoration. Hologram can also be set to appear in background. Toggles entity on/off. Toggles gas on/off. Toggles forcefield on/off. Toggles forbid on/off. Change cannon fodder Pauses gameplay and centers view on the trigger for a moment. Depending options either spawns the entity to the game or kills it. Triggers its target, turns inactive until its restored (see: restore).

[ 10 / 37 ]

hologram on use: infocomp description: InfoComp is used for all dialog, monologue and info terminals. If InfoComp is link target of some field trigger, it will appear invisible in-game and it's message is shown as player comment, otherwise it will be info terminal. In sequences also the info terminals appear invisible and their messages show up as non-player comment, while player comments are 'said' by player stand-in entity (see: AI_STANDIN of STAT). For player one-liners you can also define which voice over audio group will be used (see: VOICEOVER). on use: layer description: Renders image layer as part of the world. You can set the layer dimming and material like with envdamage, but you can also make layer unbreakable if you wish. Also, layers can be set to be rendered in background, back between parallaxes and textures. on use: lock description: Works exactly like trigger, but requires a keycard to be activated. on use: monitor description: Monitor fill tool can be set to appear as standard sized or large wall monitor. Tracking monitor will, well, track player and white noise is exactly that, white noise. In entity mode you can select the entity to be used, a bit like with guide or hologram, only the monitors will fill the entire trigger field instead of rendering just one. Monitors can be set to appear silent or noisy; Noisy monitors will play idle sound when active and flatlining beep when off. on use: Toggles between tracking and white noise screens, entity monitor is first turned off, then swapped to white noise on the second toggle. Triggers target if player has a keycard. Breaks the block or, in case of unbreakable ones, just disables it. Shows InfoComp message either as info text or as an entity dialog.

music description: Change music on the fly. You can define the transition to be an instant cut, power-down fade or basic fade out. Use string off to turn the music off. on use: platform description: Its platform moving sideways, kind of like vertical door that is hidden inside a wall when its off. Width of the platform isnt fixed, but it cant be longer than 128 pixels (8 grid units). Platform can also be used to create telescopic bridges, as its totally invisible and nonblocking when its off. on use: pulse description: Pulse is sort of a constant delay that fires its target in every defined milliseconds. As an example, pulse with 1000 millisecond delay linked to an elevator will make the elevator go up and down, changing its direction on every second. As all this kind of triggers function only when they are in visibility radius, its strongly recommended that you make pulse as wide as Turn the platform on/off. Changes or stops music.

[ 11 / 37 ]

pulse the area it affects. Pulse can start either active or inactive, requiring restoration before starting the loop (see: restore). on use: quake description: Shakes the screen by defined factor. on use: relocate description: This trigger can be used in sequences only. This is the key of creating complex entity events. During sequences the AI still works, trying to aim and follow the player, even though player entity appears invisible. With changing players location via relocation, you can have entities change their aim, movement, etc. Feel free to experiment with this one. on use: restore description: Tool to restore inactive triggers triggers that either have been already fired or ones set on purpose inactive before some event occurs. If restore is linked to multitap, it will attempt to restore all trigger fields linked within. on use: rotaway description: Again pretty much like field, but requires defined times of activation before actually firing. Like, if you make it require 5 activations, it wont fire its target until on 5th activation. on use: screen description: Large monitor screen which uses background layers for graphics instead of entities. Screen can be set to show only one of the layers, all of them as frame-by-frame animation or render the layers same way as the background parallaxes. on use: secret description: This field defines a secret area, which adds to your score when entered. on use: sfx description: Plays sound effect, either positioned to trigger origin or as global, full-volume sample. Sound effect mustve been loaded somewhere within the TAGAP_Scripts before it can be played. on use: sign description: Electric light sign or one of standard letters. You can set the text yourself. on use: Plays the sound effect. Must be entered by player to activate. If screen is set to show one of the frames, toggling changes the frame. Triggers its target after defined times of activation, then turns inactive. Makes target trigger active again or resets it to starting values. Relocates player instantly (sequences only). Shakes the screen.

[ 12 / 37 ]

sound description: Emits sound loop from trigger. Sound loops are defined in TAGAP_Scripts (see: SOUNDLOOP). on use: spawner description: Spawns an entity to the game. You can choose any entity you wish and select between standard teleportation effect or no effect at all. Spawner can be triggered unlimited times. on use: stream description: This trigger plays defined ambient stream. The default folder for these streams is data/sound/world/. To stop the stream, use string off. on use: teleport description: Teleport device. If linked to other teleport, it can be used to travel to that teleport instantly. If no link is set for current teleport, it can be used only as destination, not as transporter. on use: tempo description: Changes the spawning speed of cannon fodder. Smaller the spawning interval, more frantic waves of slaughter youll get. Use trigger fodder the change the actual cannon fodder. on use: terminal description: Computer terminal that works like trigger and can also be defined to start on or off. If no link is defined, terminal will work as monitor with computer code running on screen. on use: texblock description: Another texture block utility this time textures can be scrolled vertically or horizontally, i. e. creating moving chains or conveyors. You can set the speed from editor. on use: theme description: Trigger to switch the default level environment theme in-game (see: THEME_START). on use: ticker description: Different kind of counter that counts either from zero to defined value or the other way around. Ticker can be set to appear as counter monitor or gauge meter. You can also set the counting speed. Use restore to revert ticker back to its starting value. on use: Start counting from/to zero. Switches level environment theme. Toggles texture movement on/on. Triggers its target. Changes the tempo. Uses the teleport. Plays or stops audio stream Spawns the defined entity. Toggles sound on/off.

[ 13 / 37 ]

trigger description: Basic trigger mounted to a wall. Trigger can be defined to start either on or off. If trigger is linked to always, it will appear as simple button that can be used unlimited times, like i. e. elevator call button. on use: water description: Well, its water. Water can be crystal clear, green toxic waste, burning lava or liferegenerating clone fluid. Since edges of water area are faded, its strongly recommended to make water areas consist of only one trigger field instead of multiple ones. If you want to make completely flooded level, use level theme with UNDERWATER environment setting (see: THEME_START, ENVIRONMENT). on use: waterfall description: Surprisingly its a waterfall. Its mainly for decoration and to be used in context with related water area. Like water, waterfalls can also be water, toxic waste, lava or clone fluid. on use: window description: Kind of a specialized version of envdamage, window is used to render windows only. You can either use the default window texture by using string NULL, select a texture from list and use it like envdamage or make it appear as skybox only with string NONE. Windows can also be dimmed and forced to the background like layers, but then they can't be broken. Broken windows act accordingly to current level theme, i. e. if it's thunderstorm outside, raindrops will spatter through and raining sound and thunder are louder. on use: Triggers its target.

[ 14 / 37 ]

Basics of Scripting
Introduction to scripting
Though TAGAP_Script is intentionally left very simplistic, its still the most complex aspect of TAGAP editing. There are so many things you can do with basic commands, all sorts of hacks and combination of both, that in handbook we're not even trying to cover it all. Instead we'll focus on a couple of most asked-about subjects to get you started. Note that only a small fraction of TAGAP_Script commands are mentioned and explained here, so it's strongly recommended you'll scan through Appendix B: TAGAP_Script Syntax for the whole scripting language specs at least once. So what makes a TAGAP_Script file? They are plain text ASCII text files that start with line //TAGAP_START and end with TAGAP_END. The code is written in the between. You can add comments in C-way by placing // at the beginning of the line. Script is being read line-by-line, so splitting script command to two lines isn't allowed. Note that strings don't support spaces, so replace them with _, which will appear as space in-game. That's the very basics, now let's look at what we can do with it.

Weapons scripting
New weapons. No matter what game we're talking about, thats what people want to do first. To make a new weapon, you need to start with creating the weapon projectile entity. In TAGAP_Script, entities are defined with code block starting with ENTITY_START <entity name> and ending with ENTITY_END. Missiles have AI set to AI_MISSILE with projectile movement speed as speed value (see: THINK). Now with the graphics. The projectile needs a sprite defined (see: SPRITE) in order to appear as moving entity, otherwise it will be handled as traceline projectile, like bullets, beams and lightnings. Entity projectiles are flying by default, but you can set them ballistic, too (see: MOVETYPE). For good gameplay's sake projectiles should never have range greater than screen dimensions. To tune the range, use TEMPMISSILE relative to missile speed for entity projectiles and AI_RANGE for tracelines (for both, see: STAT). Once the weapon projectile entity has been made there are two ways to assign it for an entity; via weapon slot (see: WEAPON) or as entity missile (see: MISSILE). Weapon slots work like player's weapons and every entity can use one, all you need to do is add STAT S_WEAPON <slot> variable for them (see: STAT). As weapon slots are global, many entities can use the same exact slot, so modifications to the weapon affect every entity using the slot. Missile is handy in many occasions too, like if you want multiple entities to use the very same projectile, but handle it in different manner. This is cause non-weapon slot missiles use rate-of-fire and charge values of the attacking entity, not ones of the projectile. Note that weapon projectile that is used as a weapon slot can also be used as missile and an entity can have both weapon slot and missile defined. Weapon slots have one significant advantage; You can have more control over them. Weapon slots 09 are available for player use and use ammunition unless defined otherwise. Other entities can naturally use these slots, too. Player can also use slots beyond that, but those act as nonammo eating mounted weapons, like minigun of a chopper and when player entity uses such weapon, player can't access standard weapons. Other cool thing is, that unlike with defined missiles, entities can swap weapons too, if they're allowed to. Entity can be set to respond to each weapon individually (see: WEAPON_RESPONSE) or forced to always use the same weapon player is wielding (see: AI_COPY_PLAYER_GUN in STAT). You should think carefully which entities you'll allow to do this, however, as though it's makes cool combat situations with bosses, it goes a waste in run 'n gun levels. And don't even dare to think it's over once the weapon is slapped to the game! Oh no, now the hard part begins; Whatever weapon you choose to make, remember to balance it well. Make it

[ 15 / 37 ]

have weaknesses and strengths and keep testing and testing and testing until its perfect.

Sprites and animations

Now that your main scripting urge has been dealt with, it's time to look at sprite handling. It doesn't take long for you to notice how dull non-animated, non-interactive graphic blocks look like. First off, there are two ways of loading sprites, static and dynamic loading. Static loading means the sprite is stored in memory at all times and can be accessed at all times, while dynamic means the sprite is loaded during initialization of the level in which the object is used and flushed when that level is completed. It's strongly recommended to use dynamic loading for entities and objects used only in certain specific locations of the game, like big bosses, for instance. This way you'll save a lot of precious memory from going a waste. A word of warning, though; Never use both methods for a one sprite! If the sprite is used in one entity as static and as dynamic in another, you'll end up confusing the engine on how to handle the sprite, which may result in game crash. The main way TAGAP uses to animate entities is called parametric animation. Way more common with polygonal objects than sprites, this means that instead of animating object by displaying frame-by-frame, portions of the object are moved mathematically according to the entity's movement. An example to simplify the concept; When player runs, his legs are not animated by showing a new frame 24 times a second, but actually moving the legs. As a result the movement looks a lot smoother especially so in slow-motion and eats a lot less memory. This also allows combination of nearly infinite amount of animations, as player can aim any wanted direction without it affecting the running animation. More specific parametric animations, like weapon or leg movement, are set in sprite definition itself (see: SPRITE). In addition to these base animation styles, there are sprite variables (see: SPRITEVAR). These can be used for both additionally expand the base animation or to define more simplistic animations (rotation, scrolling, frame-by-frame animation, etc.). Read the documentation of both ways carefully and start bringing your creations to life. And, as always, feel free to experiment.

Sequences
Sequences are toughest part of scripting and really hard to describe, as they are more or less based on exploiting the game routines in every possible way imaginable. Instead, this chapter describes the basic concept of doing animation sequences in TAGAP. Perhaps the best way to start scripting a sequence is by first adding all the relevant configuration variables, or CVars (see: Appendix C: Configuration Variables, CVAR), most notably music to be played, save game allowance and level theme. Note that there's no sense in adding an audio stream at this point, as there's nothing to sync it with yet. Next, to make testing a lot easier, you should add a temporary sequence button, that restarts the sequence. This way you can run TAGAP in window and write the script and/or edit its graphics at the same time, just reloading the script in-game. To do this, use SEQUENCE and make it a sequence button, with the filename of that sequence as a target. Simple. Now once the framework is done, its time to start creating the content. Basically sequences fall into three categories; in-engine animations with entities and level objects, image layer based animations and complex combinations of both. Image layer based ones are the easier, I guess, so let's start with those. Once you have the graphics, add them in with LAYER command. The image manipulation is done with image flags (see: SEQFLAG). Scaling, moving, rotating, it's all done with those. There's no need to go into details how to do some particular trick, as you're bound to learn more from just messing around and experimenting with the flags. Just note that most of the flags can be set to affect whole scene instead of an image by using index pointer -1. Making in-engine animations is more complex and requires some experience in scripting already

[ 16 / 37 ]

under your belt. First you naturally need to make the level data and it's obviously easier to do with the level editor. Start a new map and go to geometry mode. As very first thing add two linedefs, starting from coordinates x0 y0, first vertical and 608 pixels long, other horizontal and 800 pixels long. As you must have guessed, those represent the screen dimensions for the scene to fit your scene in. You can move view, sure, but it always comes back to origin. The entities used for sequence scripting aren't shown in editor, so add something you remember to replace in their place. Save the level and open it in text editor. Now copy all the contents except CVars from the level file to the sequence script and restart TAGAP to that sequence (see: Appendix C: Configuration Variables). In the text editors swap the entities to the ones you wanted by replacing their names the positions you set in editor should be right. Save the file and hit that reload button you made first. And enjoy the show. I'm sure what you'll see as far from cool action scene you wanted to make, but it's a start. By default, the dynamic graphics are flushed every time a new script is loeaded. This is fine with simple animations of one script frame, but if you want to do more complex cinematics with timed music and audio streams, it's strongly recommended to use noreload (see: Editing Variables). Enabling that prevents graphics from being unloaded from memory, allowing loading all the graphics on starting frame, making the cinematic smoothly flow through multiple frames without any load times in between. Variable noreload reverts back to zero after each script load for obvious security reasons, so you have to enable it again before every transition beyond which you want to keep the graphics. Dynamic sprites of entities ( see: ENTITY_START, SPRITE) are also not flushed, so to preload an entity, define a spawner trigger (see: Using Triggers, TRIGGER) with the entity you need; It won't show-up if you don't activate the trigger, but it's graphics are still loaded. In creating sequences its pretty much everything goes as long as it works. If it can't be done directly, it can be hacked with workaround. And if it can't done with workaround, it can be faked. While creating the game, every time I started doing a new sequence I was surprised by the flexibility of the system, as it's simple but offers so many options. All you need is imagination and too much spare time.

[ 17 / 37 ]

Appendices
Appendix A: Editor Controls
GUI controls
F1 F3 F5 F6 F7 F8 Ctrl + S Ctrl + L Ctrl + X Ctrl + Shift + Home Ctrl + Shift + End Alt + Arrows Alt + Arrows + Shift [Switch editor mode] [Next level * / **] [Toggle between game and the editor] [Restart level *] [Editor setup] [Save level] [Load level] [Instant quit] [Delete all objects before mouse cursor] [Delete all objects after mouse cursor] [Nudge object by one pixel] [Nudge object by a half grid unit]

General editor controls

Arrows Home End Shift Alt PgUp / PgDown TAB DEL [Move view position] [Center view on player start position] [Center view on level exit trigger] [Moves entire object instead of a point] [Hold for grid-free movement] [Select next / previous object in the list] [Center view on the current object] [Deletes current object]

Geometry mode
Space Backspace C E/I/D G P T L F O M Insert [Adds a linedef] [Cancels linedef / trigger field] [Changes style of current linedef] [Adds an actor / item / decoration entity] [Copies entity or trigger, use E, I, D or P to paste] [Pastes the copied trigger] [Adds a trigger field] [Links currently pointed entity or trigger] [Select target of the current trigger] [Select owner / user of the current trigger] [Multitap editor] [Relocates the player start point]

Texture mode
R/T Space Backspace Enter G P D F H V 18 Ctrl Shift + PgUp / PgDown [Adds rectangular polygon] [Starts drawing custom polygon] [Cancels the previous polygon point] [Completes the polygon] [Copies the selected polygon] [Pastes the copied polygon] [Grab texture to fill tool] [Use fill tool on polygon] [Flip polygon horizontally] [Flip polygon vertically] [Set polygon texture offset point] [Hold for Overdose view] [Change the rendering order of polygons]

*) only available in-game; **) only available when cheats are allowed

[ 18 / 37 ]

Appendix B: TAGAP_Script Syntax

Take note that not all script commands are always accessible, like you cannot set an entire world into a sprite. Dont worry, though, all invalid script lines will be ignored by the parser and are reported in the user log. Each actual command line starts with id string that tells the script parser the form of the current command. Here is the complete list of script commands (read: [id string] <variable input type>).

Entity commands
AMMO <int #1> <int#2>
description: syntax: notes: Player ammunition for specific weapon slot. <int #1> weapon slot index ; <int #2> ammo amount Player can have up to 10 weapon slots only weapon slots 1-9 can have ammunition (see: WEAPON). Weapon 0 doesnt use ammo. However, ammo slot 1 of weapon entity is used to define clip size for weapon slot 0.

CLONE <string>
description: syntax: notes: Clones all info of an existing entity. <string> the name of the entity to clone Entity to be cloned must be defined before the clone. Useful when creating multiple similar entities, like containers spawning different goods modifications made to the original entity affects all clones.

COLLECTIVE <string>
description: syntax: notes: Defines the collective membership for an entity. <string> the name of the collective leader entity All collective members will relate to the first leader entity in the list thus allowing only one collective of each type per-map. Collective leader cannot be damaged until the members are killed. Use this if you want to do, say, generator-powered boss monster or something like that. Use GROUP for other entity grouping options (see: GROUP).

CORPSE <string> <int>

description: syntax: notes: Defines a corpse for an entity to be thrown upon death. <string> the name of the corpse entity ; <int> y-wise throwing offset (from entity origin) Corpse must be defined before it can be assigned. Most of the corpse handling is done engine-side, so you don't have to worry about how it spins etc.. Corpses can also be detailed by assigning a kill effect to damage inflicter (see: KILLFX).

DESCRIBE <string>
description: syntax: notes: Defines a description for an entity. <string> short description Descriptions are not necessary, but they aid level editing a lot. Naturally entities that cant be used in editor wont obviously need descriptions.

EFFECT <string #1> <string #2>

description: syntax: notes: Adds event effects to an entity. <string #1> event tag ; <string #2> effect to add The amount of debris is defined by the size of the entity (see: OFFSET). Event effects can also be added to kill effects (see: KILLFX). Weapon-specific effects like muzzle flashes and shell casings are controlled via effect stats (see: STAT). Possible event tags:
DYING = entity falling apart before actually dying GIB = entity blows apart WEAPON = entity attacks via shooting

Possible effects:

[ 19 / 37 ]

EFFECT <string #1> <string #2>

EXPLOSION = an explosion, refers to splash damage for size (see: STAT) EXPLOSION_PLASMA = energy explosion, refers to light colors (see: LIGHT) and splash damage (see: STAT). DEBRIS_CONCRETE = throws concrete rubble and dust DEBRIS_GLASS = throws loads of glass debris and a few metal fragments DEBRIS_METAL = throws metal fragments and smoke FORCEFIELD = creates effect of force field shutting down GORE_BLOOD = spews out blood GORE_GIBS = throws lots of blood and the severed eyeballs LIQUID_CLONE = throw drops of clone embryo liquid LIQUID_LAVA = throw drops of lava LIQUID_SLIME = throw drops of radioactive goo LIQUID_WATER = throw drops of clear water PAPER = spew some paper debris and some metal fragments SPARKS = electric spark IMPACT = laser-styled projectile impact, refers to entity light (see: LIGHT) TELEIN = teleport effect for entity appearing TELEOUT = teleport effect for entity disappearing

ENTITY_END
description: syntax: notes: Stops parsing values for entity and adds the entity to the list. Always end entities with ENTITY_END.

ENTITY_START <string>
description: syntax: notes: Starts parsing values for a new entity. <string> name of the entity Keeps parsing entity variables until entity is closed (see: ENTITY_END).

FLASHLIGHT <int #1> <int #2> <int #3> <int #4> <byte #1> <byte #2> <byte #3>
description: syntax: notes: Adds flashlight to the entity. <integer #1> flashlight origin x-axis offset ; <integer #2> flashlight y-axis offset ; <integer #3> light halo radius (in percents) ; <integer #4> light beam length (in percents) ; <bytes> light color in RGB Flashlight wont appear in fully lit levels (read: darkness set to 0, see: DARKNESS). Only one flashlight can be defined per entity, but it can bee multiplied with FX_MULTITORCH (see: STAT).

GROUP <string #1> <string #2> <int #1> <int #2>

description: syntax: notes: Adds other entity to current entitys group. <string #1> name of the entity ; <string #2> relation id ; <int #1> origin x-offset ; <int #2> origin y-offset Setting up a group affects pretty much everything in an entity, so to ensure everything works set groups at the very end of entity definition. You can also define collectives that are level-bound instead of group-bound (see: COLLECTIVE). Possible relation ids:
COLLECTIVE = creates collective union between current entity and the member MEMBER = member's death doesn't affect current entity USER = death of member immobilizes current entity

GUNENTITY <string>
description: syntax: notes: Sets an entity to be drawn as entity's weapon. <string> name of the entity to be used Entity must be defined before it can be used. You can define weapon entity for both weapon slots (see: WEAPON) or directly for an entity. By default the gun entity will be drawn after (read: in front of) it's owner; Use FX_RENDERFIRST to draw it before the owner (see: STAT).

GIB <string> <int>

description: syntax: notes: Defines an entity thrown as special debris on death. <string> name of the entity to be used ; <int> amount of debris to throw Entity must be defined before it can be used. You can define just one debris per entity. This works for items, too, but there is another, more specific function to do just that (see: ITEM).

[ 20 / 37 ]

ICON <string>
description: syntax: notes: Makes entity appear as different, separate object when used in status bar. <string> name of the entity Icon entity must be defined before using. If no icon is defined, the entity will be rendered to status bar as-is. Boss gauge of AI_BOSS (see: STAT) requires that entity has an icon.

ITEM <string> <int>

description: syntax: notes: Defines an entity to be dropped when the current entity dies. <string> name of the entity to be spawned ; <int> item dropping y-offset (from spawner origin) To-be-spawned entity must be defined before the spawner. ITEM can also be used to spawn other entities than just items, like smoke generators for flamethrower or ejecting pilot for destroyed chopper. You can define up to three items per entity. If that isn't enough, you can use gibs for more flying debris (see: GIB).

KILLFX <string>
description: syntax: notes: Defines kill effect entity for weapon entity. Used in weapon definition scripts. <string> the name of the effect entity The basics are as follows; When entity (projectile or a character) with assigned kill effect kills an actor with assigned corpse (see: CORPSE), that corpse will inherit special effects of the kill effect. For example if kill effect creates smoke, then the flying corpse will also create smoke. Use STATs and EFFECTs to add effects to kill effect (see: STAT, EFFECT). Effect must be defined before it can be assigned.

LIGHT <int #1> <int #2> <byte #1> <byte #2> <byte #3>
description: syntax: notes: Lits the entity with RGB-colored light. <int #1> light radius (in percents) ; <int #2> light intensity (in percents) ; <bytes> light color in RGB Lights with radius or intensity of 0 or lower are considered invalid. Light is emitted from the entity origin. Only one light can be defined per entity. The light is halo by default, but it can be turned into beam with FX_LIGHTBEAM (see: STAT).

MISSILE <string>
description: syntax: notes: Sets a projectile to be spawned on attack. <string> name of the entity to be spawned To-be-spawned entity must be defined before the spawner. Can also be used to spawn other entities than just missiles. Use offset variable WEAPON_MISSILE (see: OFFSET) to set the launching offsets different than the engine default and status variable MISSILE_OFFSETRADIUS to define the aiming radius (see: STAT). You can randomize the fired entity with MISSILE_RANDOMIZER (see: STAT). To add multiple weapons combine projectile definition with weapon slots (see: STAT and WEAPON).

MOVETYPE <string> <float>

description: syntax: notes: Sets movement type for an entity. <string> movement style tag ; <float> speed of movement Everything is NONE by default, except missiles, which are FLY. Possible movement styles:
NONE = static FLY = flying movement WALK = affected by gravity.

OFFSET <string> <float #1> <float #2>

description: syntax: notes: Defines a offset value for an entity. <string> variable name ; <float #1> x-offset ; <float #2> y-offset Be careful with missile offset values values outside entity physical size will allow it to fire through walls. For nonweapon slot based missiles use STAT MISSILE_OFFSETRADIUS (see: STAT) to define radius distance different from entity's size. For effect offset based on entity facing use status variable FX_OFFSXFACE (also see: STAT). Variable references:
CONST_VELOCITY = constant velocities (not very practical for in-game AI, but useful in creating sequences) FX_CONSTANT_FLOAT = time and range modifier for constant, non-origin related floating

[ 21 / 37 ]

OFFSET <string> <float #1> <float #2>

FX_DEATHEFFECT = debris spawning area of large entities dying (default is entity size) FX_OFFSET = fixed special effect offset (from entity origin) MODEL_OFFSET = offset when used as a weapon model (from entity origin) SIZE = entity dimensions (collision sphere size and height) WEAPON_CASING = shell casing / bazooka debris offset (from weapon origin) WEAPON_MISSILE = missile launching offset (from entity origin) WEAPON_OFFSET = muzzle flash offset (from weapon origin) WEAPON_ORIGIN = weapon sprite offset (from entity origin)

SCISSORS <int #1> <int #2> <int #3> <int #4>

description: syntax: notes: Adds scissor area rectangle that will cut out portions of sprite that exceed the defined area. <int #1> area start x-offset ; <int #2> area start y-offset ; <int #3> area width ; <int #4> area height Scissor usage is toggled with STAT FX_SCISSOR (see: STAT). If entity is part of a group, scissor area of group originator is used instead. Area doesnt affect weapon sprites during their normal state, preventing them from getting oddly clipped during aiming.

SOUND <string #1> <string #2>

description: syntax: notes: Defines a sound for an entity action. <string #1> sound event ; <string #2> sample name Name of S_VOICEOVER doesn't refer to a sample, but to a predefined voiceover group (see: VOICE, VOICEOVER, VOICEOVER_END). Only one sound can be defined per event. Non-moving, static entities wont naturally make a movement sounds. You can make all entity's sounds global instead of positional with FX_GLOBAL_AUDIO (see: STAT). S_SONG_DIE can be made to use music transitions (see: FX_TRANSITION in STAT), by default it instantly cuts to new song. Possible event references:
S_ATTACK = entity attacks S_COUGH = coughing for air S_DIE = entity dies S_DYING = large entity falling apart just before dying S_IDLE = idle sound to play looped when awake and active S_MOVE = sound of movement S_PHYSICS = physics impact sound S_RESPAWN = resurrection effect S_SLEEP = entity deactivates S_SONG_DIE = sound played on death (resume resumes level music) S_SONG_WAKE = sound played on awakening S_VOICEOVER = player voice-over on death S_WAKE = entity activates / kill effect fraggin'' sound

SPRITE <string #1> <bool> <string #2> <int #1> <int #2> <string #4>
description: syntax: Defines a sprite for an entity. <string #1> sprite loading parameter (STATIC or DYNAMIC) ; <bool> sprite full bright flag ; <string #2> animation style ; <int #1> sprite x-offset from entity origin ; <integer #2> sprite y-offset from entity origin ; <string #4> sprite name If sprite is used frequently in the game, it should be set STATIC (it's loaded once). If, however, it's huge and / or part of a boss used in only one level, make it DYNAMIC (it will be loaded only when it's used and flushed after) or use layer for a sprite (see: SPRITEVAR). Remember, though, that the same sprite should never be loaded as both dynamic and static, as it ultimately makes the engine confused and messes up the rendering. Sprites with pan animation are handled like textures and must be sized power of two (see: TAGAP Engine Introduction: File types) to be rendered. For more sprite handling parameters, see: SPRITEVAR. Possible animation flags:
ANIM_FACE = head movement and eye animation ANIM_PANFORWARD(/BACK/UP/DOWN) = constant panning forward (/back/up/down) ANIM_PANATTF (/B/U/D) = attack panning forward (/back/up/down) ANIM_ROLLATT = attack rotation ANIM_ROLLHIDE = hatch rotation animation ANIM_ROLLVEL = velocity based rotation ANIM_WEAPON = weapon animation with parametric recoil ANIM_WEAPON2 = defines sprite a akimbo-only weapon NONE = no animation

notes:

SPRITEVAR <int #1> <string> <int #2>

description: syntax: notes: Additional sprite variable. <int #1> index of the sprite ; <string> variable name ; <int #2> value (not used with variables marked as [toggle]). Status variable references:
ACTIVE = rendered only when entity is active [toggle] AIM = uses standard aiming angle for sprite angle [toggle]

[ 22 / 37 ]

SPRITEVAR <int #1> <string> <int #2>

ANGLEFACTOR = sprite angle multiplier in percents (default is 100) ANIMATE = standard frame-by-frame animation (value is speed in percents) ANIMATE_TO = same as ANIMATE, but stops when to the final frame (value is speed in percents) BIAS = walk movement angle BOB = up n down walk movement CHARGE = weapon charge animation [toggle] DIM = dimming transparency [toggle] FACE = flip sprite according to specified boolean face (doesn't flip offset coordinates) FLICKER = flickering transparency [toggle] HIDE_MOVE = entity moves y-wise by defined amount upon activation INACTIVE = rendered only when entity is inactive [toggle] INVERTFACE = draws sprite using inverted face[toggle] KEEPFRAME = uses defined frame instead of animation defaults (value -1 disables previously defined KEEPFRAME) LAYER= use defined image layer instead of sprite graphics (see: LAYER) PULSE = pulse animation, value works as speed modifier (for hearts, speakers, etc.) NOGROUND = ignores ground angle with BIAS [toggle] NOFACE = ignores sprite face (also affects offset coordinates) [toggle] ROLL = simplistic roll animation SCALE = sprite scale in percents (default is 100)

STAT <string> <int>

description: syntax: notes: The common way of defining a value for an entity. <string> status variable name ; <int> value (not used with variables marked as [toggle]). Status variable references:
AI_ACID = makes entity an acid trip hallucination [toggle] AI_AIM_OWNER = keeps aiming at owner instead of player [toggle] AI_AMMO_ALL = spends all remaining ammo [toggle] AI_AMMO_PICKUP = can be picked up by pressing [Use], thus adding it's AMMOLIFE to defined weapon slot AI_AMMO_SPEND = defines how many rounds of ammo the weapon will spend (default is 1) AI_AMMOLIFE = ammo equals life [toggle] AI_BOSS = defines the entity a boss (boss gauge requires an icon, see: ICON) [toggle] AI_BURST = amount of rounds per fired burst AI_BURST_TIME = time between bursts (in milliseconds) AI_COPY_PLAYER_GUN = always uses same weapon as player [toggle] AI_DARKNESS_ACTIVE = when set, entity is active only when theme darkness is equal or less than this value AI_DEATHJUMP = Super Mario styled dying jump [toggle] AI_DEATHJUMP_NULL = makes entity perform death jump instead of dying when it expires [toggle] AI_ENDING = end-level-on-death [toggle] AI_EXPO = item is handled as pill for achievements (items only) [toggle] AI_FINALE = final boss death effects [toggle] AI_FIRE_ON_ACTIVE = performs an attack on activation [toggle] AI_IGNORE_ONEUPS = kills the opponent regardless of any one-ups it may have [toggle] AI_INHERIT_ANGLE = for spawned entities, makes them always user owner's angles [toggle] AI_INHERIT_FACE = for spawned entities, makes them always use owner's facing [toggle] AI_INVULACTIVE = invulnerable when inactive [toggle] AI_HIDE = enables hide AI with visibility (time in milliseconds) AI_HIDETIME = hide AI hiding time (in milliseconds) AI_KEEP_IN_WATER = entity stays in water area [toggle] AI_KEEPANGE = sets constant, user-defined angle AI_KEEPACTIVE = keeps active, ignoring engine deactivation and no-aim [toggle] AI_KEEPACTIVE_FODDER = toggles AI_KEEPACTIVE if the entity is spawned as cannon fodder [toggle] AI_KEEPFACE = keeps own or group leaders face when aiming [toggle] AI_LIMIT_ANGLE = limits aiming angle AI_LIST_ALIAS = show entity in non-default entity list (1=actor, 2=item, 3=decoration) AI_LOCK_ON_FIRING = stops aiming while attacking [toggle] AI_NOBOUNCE = makes falling missiles to blow on contact instead of bouncing (see: MOVETYPE) [toggle] AI_NUMB = stays numb on activation (time in milliseconds) AI_RANDOMIZE_SPEED = walking / flying speed randomizer (in movement units times 100) AI_RANGE = pattern movement range from origin / range of trace attack AI_REPEL = makes zombies turn away from the entity on collision [toggle] AI_SIZE = AI size modifier (affects damage knock back, falling effects, etc.; default is 0) AI_SLOWMOVE = defines movement animation speed (in percents) AI_SPAWNLIMIT = maximum amount of entities allowed to be spawned AI_SPINAIM = spins aiming angle and keeps firing [toggle] AI_STANDIN = makes entity act as player standing for message quotes during sequences [toggle] AI_TEMP_ON_ACTIVE = initiates the missile temporary life span on activation [toggle] AI_TRIGGER_DISABLE = disable AI_TRIGGER_ON_DEATH if entity runs out of one-ups AI_TRIGGER_ON_DEATH = defines a trigger field to be fired on death use with extreme care! AI_UNLOCKABLE = makes weapon available only after it has been unlocked [toggle] AI_WEAPON_NOFLIP = designed for player only, prevents weapons from being flipped [toggle] CHARGE = weapon charging time (in milliseconds) DAMAGE = amount of direct damage inflicted when attacking DAMAGE_ORGANIC = attack damage is inflicted only to bleeding objects [toggle] DAMAGE_OWNER = makes player missiles damage player also [toggle] DAMAGE_SHIELD = percent of damage entity takes when attacked (default is 100) DAMAGE_SHOCK = shows damage as electric shock [toggle] DAMAGE_SPLASH = explosion damage blast radius (can be used without inflicting damage) FRAG = destroying this entity will count in killing combos [toggle] FX_360 = emits halo-ripples from the entity [toggle] FX_ACTIVATION_SPARK = create a spark from weapon on entity activation [toggle]

[ 23 / 37 ]

STAT <string> <int>

FX_BAZOOKA = bazooka back smoke [toggle] FX_BREATHE = makes entity breathing, creating effects when necessary FX_BULLET = makes trace attack to be drawn as bullet (not fully supported by impaling attacks) [toggle] FX_CASING = shell casing type FX_CLOAK = makes entity cloaked except when damaged (value is time uncloaked in milliseconds) FX_DIM = makes the entity light dim (0 is default dim, while negative and positive values alter the cyclic speed) FX_DIM_COLOR = renders entity with dim background color instead of foreground color [toggle] FX_DISABLE = disables particle and flash effects [toggle] FX_DROPDEBRIS = drops the death debris instead of throwing [toggle] FX_ELECTRIC = electricity effect [toggle] FX_ELECTRIC_LIT = electricity effect bound to light size and color [toggle] FX_EXPAND = expands entity towards removal (i.e. flame) [toggle] FX_FADE = fades entity to nothing instead of standard effects [toggle] FX_FLASH_ATTACK = screen flash glare applied on attack (in percents) FX_FLICKER = flickering light effect [toggle] FX_FLOAT = adds y-wise floating [toggle] FX_FORCEWALL = temporary force field effect based on entity's physical size [toggle] FX_GLOBAL_AUDIO = makes all entity sounds audible everywhere [toggle] FX_GLITTER = glitter glitter [toggle] FX_IDLEDISTANCE = audibility distance of idle sounds in percents (default is 40) FX_KEEP_EFFECTS = render effects even when entity is inactive [toggle] FX_LIGHT_ON_OFF = forces entity light to use engine on/off values instead (green/red) [toggle] FX_LIGHTBEAM = entity light beam length (in pixels) FX_MULTITORCH = multiplies the flashlight effect FX_MUZZLE = size of the muzzle flash (in percents) FX_NOENV_FX = disables environmental effects light glare and rain [toggle] FX_NOFACE = ignores facing changes [toggle] FX_NOSOUND = disables automatic (non-user-defined) sounds [toggle] FX_OFFSXFACE = particle effect x-offset (uses face) FX_PANSPEED = sprite panning speed for entity (in percents from default) FX_PLASMA = spawns sparks referring to entity light color [toggle] FX_POWERUP_SIZE = defines the size of power-up effects (default is collision sphere size) FX_PUSHUP = recoil pushes weapon upwards when firing [toggle] FX_RENDERFIRST = render additional models before entity [toggle] FX_SCALE_ITEM = size of entity sprite when appearing in status bar (in percents) FX_SCISSOR = enables scissoring [toggle] FX_SMOKE = adds particle smoke trail [toggle] FX_SMOKE_ANGLE = override angle for smoke FX_SMOKE_SHOOT FX_SMOKE_FLOOR = particle smoke from ground when moving [toggle] FX_SMOKE_SHOOT = shoots out smoke to aiming direction (value is smoke size in percents) FX_SOUND_ON_FIRST = plays attack sound only on the first round of a burst [toggle] FX_SPARKS = adds particle sparks [toggle] FX_SPIN_ATTACK = spin weapon on attack instead of firing [toggle] FX_SPIN_CHARGE = spin weapon on charge instead of glow [toggle] FX_SPIN_MOUNT = mounts gun, preventing spin kick and using alternate method for fullmodel angles [toggle] FX_TELEATTACK = applies teleport attack effect for missiles FX_TRANSITION = makes S_SONG_DIE (see: SOUND) to use transition (1 = power down ; 2 = fade out) FX_WADDLE = rapid waddle bias on death [toggle] FX_WADDLE_AIM = constant aim waddling range FX_WADDLE_CONSTANT = constant bias waddling range FX_WALK_SHAKE = room shaking applied upon movement (shake multiplier in percents) FX_WEAPON_FRAME = overrides weapon slot based weapon frame with defined frame HIGHROF = super rate-of-fire (multiple shots per real-time frame) IMPALE = number of entities trace attack will blow through INVISIBLE = hidden while inactive [toggle] MISSILE_OFFSETRADIUS = projectile launching radial offset MISSILE_OFFSETWADDLE = makes projectile offset waddle by defined pixels MISSILE_RANDOMIZER = projectile entity randomizer value MODELHACK = weapon model hack, defines entire character a weapon [toggle] MULTISHOT = makes weapon shoot multiple rounds at a time NOLIST = doesnt show entity in editor (useful for groups, scripts, etc.) [toggle] REVIVE = for items, restores player to full health S_AKIMBO = guns akimbo S_EXTRALIFE = extra life quantity S_HEALTH = entity life points S_IDDQD = gives invulnerability time (in integer seconds) S_KEY = keycard quantity S_OVERDOSE = gives overdose time (in integer seconds) S_QUAD = quad damage time (in integer seconds) S_SCORE = points gained from scoring (killing of picking up) S_SPEEDUP = gives speed-up and flying time (in integer seconds) S_WEAPON = weapon slot index SCORE = points gained from scoring (killing or picking up) TAKEDAMAGE_BLEED = bleeds and takes damage [toggle] TAKEDAMAGE_ELECTRIC = non-organic, but sparkles and takes extra damage from electricity [toggle] TAKEDAMAGE_ENV = takes damage like environmental texture objects [toggle] TAKEDAMAGE_NONE = doesnt take damage (same as default, toggle) TAKEDAMAGE_PLASMA = energy object that takes damage [toggle] TAKEDAMAGE_SURFACE = non-organic but takes damage [toggle] TAKEDAMAGE_UNBREAKABLE = unbreakable, solid, cant be damaged [toggle] TEMPMISSILE = life span when fired as a missile (in integer milliseconds)

[ 24 / 37 ]

TEXPOLY <string>
description: syntax: notes: Adds a texture block centered on the entity start origin. <string> texture image filename Being mainly designed for making background mount for static actors like turrets, this command is not that practical with moving entities. If the texture name begins with '(' the texture remains exclusive and doesn't show up in the editor's texture list. If you wish, you can clone it (see: TEXCLONE) to list it. Also texpolys can have assigned entities (see: TEXLITE), but it's not very practical since these are already entity-bound. Remember, though, that textures are always loaded to memory, so if this entity of yours appears rarely and/or is huge, you'd better use either layer or hologram triggers instead with dynamically loaded graphics (see: TRIGGER, LAYER).

THINK <string #1> <float #1> <string #2> <float #2>

description: syntax: notes: Defines the AI routine used for the entity. <string #1> main AI routine reference ; <float #1> speed modifier ; <string #2> attack AI function reference ; <float #2> delay between attacks (in seconds) If no main AI reference is defined the entity will be handled as a static decoration. AI reference AI_MISSILE applies the attack method AI_BLOW by default. Possible main AI references:
AI_AIM = constantly aims at the player, aim affects flying direction AI_CONSTANT = for use with collectives, keeps constant distance to the leader AI_FOLLOW = follows the player until reaches attack range AI_ITEM = an item AI_MISSILE = weapon projectile AI_USER = player-controlled AI_WANDER = flying entity which wanders around its owner AI_ZOMBIE = walks straight until hits wall or dies NONE = static entity

Possible attack references:

AI_FIRE = fires a missile AI_BLOW = acts like missile on impact AI_MELEE = attacks when player is within touch NONE = no attack

VOICE <string>
description: syntax: notes: Adds a sample into player voice over group (see: VOICEOVER, VOICEOVER_END). <string> sample name Samples are loaded from data/sound/voiceover folder.

VOICEOVER <string> <bool>

description: syntax: notes: Starts defining player voice over group. <string> group name ; <bool> play once flag Keeps parsing voice over samples until group is closed (see: VOICE, VOICEOVER_END). Group name is used to determine which group to play. You can name them how you please, except for the first group, which has to be NULL for compatibility. If play once flag is true (1), group won't play multiple times in a row that group won't be played again until some other group is played in between. You can define death comments for entities (see: SOUND) or use trigger infocomp to create even more specific voice over events (see: Using Triggers: infocomp, TRIGGER). Obviously group must've been defined before it can be used.

VOICEOVER_END
description: syntax: notes: Closes player voice over group.

WEAPON_RESPONSE <int #1> <int #2>

description: syntax: notes: Responds to player's weapon by switching own weapon according to the scripting. <int #1> weapon slot to respond to (0-9) ; <int #2> weapon to use against player's gun Entity's weapon response can be any of the available weapon slots (see: WEAPON). If there's no scripted response for player's weapon, the entity's default weapon (S_WEAPON, see: STAT) will be used. If you want the entity to always use same weapon as the player, use AI_COPY_PLAYER_GUN (see: STAT); That way you need to add weapon response details only for slots you don't want the entity to access.

[ 25 / 37 ]

Definition commands
BACKGROUND_TO_DIM
description: syntax: notes: Makes on-background (dimmed) portions of the screen to use background color shifting instead of the default front shifting. Used in map themes (see: THEME_START, THEME_END). Always active in case of overdose effect themes.

CANNONFODDER <int> <string>

description: syntax: notes: Defines an cannon fodder list entry. <int> index of the fodder list ; <string> name of the entity to add To-be-spawned entity is picked random from the chosen list. List indexes start from 1 (0=off).

COLOR <bool #1> <bool #2> <byte #1> <byte #2> <byte #3>
description: syntax: notes: Defines the lighting colors for a theme. Used in map themes (see: THEME_START, THEME_END). <bool #1> part to affect (0=world ; 1=backgrounds) ; <bool #2> shift state to define (0=base ; 1=target value of color shift) ; <bytes> color in RGB format Theme colors can be static or made to shift in various ways (see: SHIFT).

CVAR <string #1> <int / string #2>

description: syntax: notes: Stands for configuration variable and is used for storing engine configurations. <string #1> variable name ; <int> numerical value ; <string #2> string value Use either numerical or string value, not both. There are two types of CVars those that are automatically stored into user configuration and those that are used for game scripting. See Configuration Variables for Game Editing for editing variables and Troubleshooting Handbook for system configuration variables as well as command line usage. CVars are registered engine-side, so you cannot create new CVars through scripting.

DARKNESS <int #1> <int #2>

description: syntax: notes: Defines the intensity of the darkness effect. Used in map themes (see: THEME_START, THEME_END). <int #1> base darkness ; <int #2> shifted darkness Darkness intensity ranges from 0 (over bright) to 3 (pitch black). Normal darkness is 1. Shifted darkness is only used by DELAY shifting (see: SHIFT). Not supported by overdose effects, they always refer to values defined of currently active theme.

ENVIRONMENT<string>
description: syntax: notes: Defines the environment style for theme. Used in map themes (see: THEME_START, THEME_END). <string> environment style Not supported by overdose effects. Possible environment styles:
RAIN = heavy exterior rain RAININT = interior with heavy rain falling outside SNOW = breezing cold with snowing UNDERWATER = completely flooded underwater setting

FONTW <int #1> <int #2 #17>

description: syntax: notes: Defines width of font characters per line in font textures. Used in game definition script. <int #1> line in texture (0-5) ; <int #2 #17> character widths in pixels Character width is one of a character in texture. It is strongly recommended, though not required, that all the numerals are of equal width, as different width results slight but visible fluctuation in status display counters, which doesn't look good. Width of numeral characters in default font is 21 pixels.

GRAVITY <int>
description: syntax: Defines gravity for theme. Used in map themes (see: THEME_START, THEME_END). <int> gravity in percents of normal

[ 26 / 37 ]

GRAVITY <int>
notes: You don't need to define gravity if it's the default 100%. Not supported by overdose effects.

GUISTR <string #1> <string #2> <string #3> <string #4>

description: syntax: notes: Defines string to be used in GUI. Used in GUI scripts. <string #1> string reference id ; <string #2> item name ; <string #3> help line ; <string #4> help line Menu ids must start with character '_', editor strings with '*' and sequence strings with '+'. This way you can have same id with different content (i.e. _save and *save). String id must not be longer than 16 characters. Though used ids of menu and editor strings are fixed in-engine, you can make your own strings for sequences (see: SEQUENCE).

INCLUDE <string>
description: syntax: notes: Includes a new script file to be loaded on start-up. Used in game definition script. <string> name of the script file to include Scripts will be loaded in the order specified.

SHIFT <bool> <string> <int #1> <int #2>

description: syntax: notes: Defines color shifting for the level theme. Used in map themes (see: THEME_START, THEME_END). <bool> part to affect (0=world ; 1=backgrounds) ; <string> style ; <ints> speed modifiers for the shifting cycle DELAY shifting intervals can be randomized (see: SHIFTRAND) and/or it can make a sound (see: SHIFTSOUND). Styles:
NONE = static PULSATE = pulsating DELAY = delayed sharp-cutting shifting (modifiers equal time delay in milliseconds)

SHIFTRAND <bool> <int #1> <int #2>

description: syntax: notes: Randomizes theme color shifting modifiers. Used in map themes (see: THEME_START, THEME_END). <bool> part to affect (0=world ; 1=backgrounds) ; <ints> max random value added to speed modifiers Supported only by DELAY color shifting (see: SHIFT).

SHIFTSOUND <string> <bool>

description: syntax: notes: Sound played during theme color shifting. Used in map themes (see: THEME_START, THEME_END). <string> sample name ; <bool> toggles ambient exterior effect Shifting sound is only played by DELAY shifting (see: SHIFT). Not supported by overdose effects.

SOUNDLOOP <string #1> <string #2>

description: syntax: notes: Defines a sound loop for sound trigger field to choose from. <string #1> sound loop reference name ; <string #2> loop sample name It's not recommended to use sounds that are defined as non-looping as looping and vice versa. Usage of OGG Vorbis format is strongly recommended in case of long loops because of smaller files. Once loop is defined it can be used with trigger sound (see: TRIGGER, sound).

STREAM <string>
description: syntax: notes: Defines background audio stream to be played. Used in map themes (see: THEME_START, THEME_END). <string> stream name All stream loops are streamed from sound/world folder. Streamed audio should be full stereo. Not supported by overdose effects. Doesn't affect sequences to avoid conflicts with sequence streams.

TEXBRIGHT <string>
description: syntax: Makes texture completely fullbright without need of adding separate fullbright texture. <string> name of the texture

[ 27 / 37 ]

TEXBRIGHT <string>
notes: Comes very handy in creating light sings etc. without wasting memory for nothing.

TEXCLONE <string #1> <string #2> <bool>

description: syntax: notes: Clones a texture. <string #1> name of the clone ; <string #2> name of the texture to clone ; <bool> toggles full bright of original texture for the clone Mainly used in creating effect-free versions of already lit or entity-assigned textures. Always create a clone instead of duplicating the image file, thus avoiding needless memory wasting. You can also clone engine-defined textures and entity texpolys (see: TEXPOLY) to be used in editor; In this case the texture has to be defined before creating a clone.

TEXDAMAGE <string #1> <string #2>

description: syntax: notes: Defines a damaged equivalent for a texture. <string #1> name of the texture ; <string #2> name of the damage texture Designed for use with trigger envdamage (see: TRIGGER, envdamage).

TEXLITE <string #1> <string #2> <int #1> <int #2>

description: syntax: notes: Adds an entity for texture polygon. <string #1> texture name ; <string #2> entity name ; <int #1> entity x-offset (in percents of texture image size) ; <int #2> entity y-offset (in percents of texture image size) Both the texture and entity have to be defined before using this command. This was originally designed to add texture lights, but it works with all entities. Use texture clones (see: TEXCLONE) to add different effect variations to do this, create a clone before assigning any entity to the original texture. You can also add entities to texture clones and entity texpolys (see: TEXPOLY).

TEXMODULATE <string> <float> <int>

description: syntax: notes: Makes fullbright of a texture to be parametrically animated or modulated. <string> name of the texture ; <float> amount of modulation ; <int> direction The texture must naturally have a fullbright overlay in order to get the modulation to work. Directions are: 0 = x-wise ; 1 = y-wise ; 2 = round. Modulation works for all sorts of texture objects.

THEME_END
description: syntax: notes: Stops parsing values for a level theme.

THEME_START <string>
description: syntax: notes: Starts defining a level theme. <string> name of the theme Keeps parsing values until THEME_END. If the name starts with '_' it will be handled as overdose effect instead of level theme.

WEAPON <int> <string #1> <string #2> <string #3>

description: syntax: notes: Defines a weapon slot. <int> weapon slot (0-31) ; <string #1> primary weapon entity name ; <string #2> secondary weapon entity name ; <string #3> weapon display name Weapon entity must be defined before the weapon itself. Use status variable S_WEAPON to define active weapon slot for an actor entity (see: STAT) or use weapon response scripting (see: WEAPON_RESPONSE). Player can use weapons 0-9 if ammunition is available (see: AMMO), so use slots 10 and above for non-player weapons. To add multiple weapons combine weapon slots with projectile definition (see: MISSILE).

[ 28 / 37 ]

Scripting commands
ENTITY_SET <string> <int #1> <int #2> <int #3> <bool>
description: syntax: notes: Adds a new entity into a desired location. <string> entity name ; <int #1> entity x coordinates ; < int #2> entity y coordinates ; <int #3> entity facing or angle ; <bool> activity state (0 = active ; 1 = inactive) In case of AI_AIM entity facing is actually the default aiming angle in integer degrees, otherwise it's boolean representing left/right). In case of player character, setting entity inactive makes it teleport in in the beginning of the level and/or sequence.

LAYER <int #1> <int #2> <int #3> <int #4> <string> <int #5>
description: syntax: notes: Adds a image layer that can be used as parallax background, static image or even sprite. Used in level and sequence scripts. <int #1> scrolling speed multiplier ; <int #2> layer y-axis offset from the top of the screen ; <int #3> x-wise movement speed ; <int #4> y-wise movement speed ; <string> texture filename <int #5> in-game rendering flag Use status variable FX_LAYER_SPRITE to use specific image layer as a sprite (see: STAT). Use movement speed 0 for still images. In case of sequence script the scrolling speed multiplier works as a x-axis offset. Sequence images are manipulated with SEQFLAGs (see: SEQFLAG). Use 32 bit parallaxes only when absolutely necessary large ones are major slowdown on older video cards with poor fill rate.

LINEDEF <int #1> <int #2> <int #3> <int #4> <int #5>
description: syntax: notes: Stands for line definition and adds a new geometry line into the map. <int #1> starting point x coordinate ; <int #2> starting point y coordinate ; <int #3> ending point x coordinate ; <int #4> ending point y coordinate ; <int #5> style flag Linedefs are used as floors, ceilings and walls for physics calculations. Style flag defines the linedef facing and style (0 = floor or facing left ; 1 = ceiling or facing right ; 2 = plate floor ; 3 = plate ceiling). Incorrect face may result incorrect entity movement and awkward collision events.

LINK <int> <string>

description: syntax: notes: Adds a multitap link. Used in level multitaps (see: MULTITAP, MULTITAP_END). <int> target index ; <string> link class Link class LNK_NONE is disabled from multitaps as a complete waste-of-space. Possible link classes are LNK_ENTITY (entity link) and LNK_TRIGGER (trigger link). For safety reasons multitaps cannot be linked to other multitaps by class LNK_MTAP, like triggers.

MESSAGE
description: syntax: notes: Starts parsing info message. Keeps parsing message lines until message is closed (see: MESSAGE_END). Messages are referred to by trigger infocomp (see: TRIGGER, infocomp).

MESSAGE_END
description: syntax: notes: Closes current message. Always close messages with MESSAGE_END.

MESSAGE_LINE <string>
description: syntax: notes: Adds a line into current message. Used in message scripts (see: MESSAGE, MESSAGE_END). <string> message line

MULTITAP
description: Starts parsing multitap controller.

[ 29 / 37 ]

MULTITAP
syntax: notes: Keeps parsing multitap links (see: LINK) until the device is closed (see: MULTITAP_END).

MULTITAP_END
description: syntax: notes: Closes the current multitap. Always close multitaps with MULTITAP_END.

POLYGON <string> <int> <bool>

description: syntax: notes: Starts parsing a polygonal texture shape. <string> texture name ; <int> polygon point used as the texture offset ; <bool> texture shading (on/off) Keeps parsing polygonal shape until the shape is closed (see: POLYGON_END, POLYPOINT). The order of polygons in the script equals to the order they are drawn to the world.

POLYGON_END
description: syntax: notes: Closes the current polygonal texture shape. Always close polygons with POLYGON_END, not by re-entering the first polypoint.

POLYPOINT <float #1> <float #2>

description: syntax: notes: Adds a new point to the current texture polygon. Used in polygons (see: POLYGON, POLYGON_END). <float #1> point x coordinate ; <float #2> point y coordinate Polygon must have at least three points to be valid.

SEQFLAG <string> <int> <float #1> <float #2>

description: syntax: notes: Adds sequence image layer rendering flag. Used in sequence scripts. <string> flag id ; <int> index of affected image ; <float #1> speed / offset ; <float #2> distance / amount value Used to animate sequence images (see: LAYER). The speed / offset value defines the direction (positive or negative) and amount value works as a target multiplier. Creating picture box BUTTON requires two images (normal and mouse hover version). Sequence flags are private for each sequence script, so when keeping images in memory during multiple sequences (see: noreload in Editing Variables, CVAR), they can be manipulated independently on each frame. All flags except BLIT, BLITCONSTANT, BLITRANDOM, BUTTON, DISABLE, FADE, FRONT, RELOCATE and REPEAT can be set to affect the entire scene; Just set image index to -1. Possible flag ids:
BLANK = image is used for blank items and isnt shown BLIT = draws image for a amount period of time (speed defines invisibility time) BLITCONSTANT = defines a delay during which layer manipulation, like movement, is disabled BLITRANDOMIZE = image blit value randomizer BUTTON = transforms GUI item into button (offset is image state 1 or 2, amount is GUI item index) DIM = dim shading, amount equals time spent fully lit, 0 or below makes pulsing image DISABLE = prevents layer from being rendered (in case of images loaded in previous sequence). FADE = fades invisible, works like dim FRONT = defines the image rendering layer (from 0 to 3; use -1 to make image appear only as parallax) MAGNIFY = same as zoom, but from original image to full * amount size MOVEX / MOVEY = moves image to its position from offset in time / amount RELOCATE = relocates layer image that has been loaded in previous sequence REPEAT = makes non-ARB image repeated texture (values represent added width and height) ROTATE = rotates image until angle is amount (amount 0 is unlimited rotation) SCISSOR = scissor area (value = start x ; amount = start y ; scene only) SCISSORSIZE = scissor area size (value = width ; amount = height ; scene only) ZOOM = zooms to or out from full * amount sized image

SEQSOUND <int #1> <int #2>

description: syntax: notes: Defines a sound to be played for sequence button item. <int #1> button item index ; <int #2> sound index Sound will be played when active button item is used. Basic user interface sounds are indexed from 0 to 6. Only sounds defined in-engine can be used (user-defined in-game samples aren't available).

[ 30 / 37 ]

SEQUENCE <string #1> <int #1 / float> <int #2 / string #2> <string #3> <int #3> <string #4>
description: syntax: General sequence scripting command with two different possible syntaxes. Used in sequence scripts. <string #1> command id ; <int #1> x-wise offset ; <float> timer time (in milliseconds) ; <int #2> y-wise offset ; <string #2> timer command id ; <string #3> output text string / timer command string value <int #3> item layer (non-timer) ; <string #4> hyperlink (non-timer) Possible timer commands are MAP (go to the next map) and SEQ (activate another sequence). Use TIMER command id to activate timer parsing. See LAYER for sequence image handling. Item layer 0 means it will be drawn into sequence itself and it is affected by all fade and glare effects. Layer 1 is for active items, which are never faded or glared. Remember to define a hyperlink even for non-hyperlinks to avoid parser errors (use _). For text items use negative layer value for alternate alignment (-1 = left, -2 = center, -3 = front center). To use GUI strings with hover help, use output text (see: GUISTR). Possible command ids:
FREEZEAI = freezes all AI activity (timer only) MAP = go to the next map NEWGAME = start a new game RESTART = restart from beginning of the previous level SAVE = brings up the save game list for saving SCORE = prints the current contents of a Cvar (use hyperlink value) SEQ = activate another sequence STOPSOUND = stops all sound effects (timer only) STOPSTREAM = stops audio stream nut music and effects will continue (timer only) TEXT = bright text string TEXT_DIM = darkened text string TEXT_LARGE = large, bright text string TEXT_LARGE_DIM = large, darkened text string TEXT_WHITE = white, null text string TEXT_WHITE_DIM = darkened white text string TIMER = sets a timer

notes:

SEQTIMER <int> <float>

description: syntax: notes: Sequence trigger timer. Used in sequence scripts. <int> index pointer of the trigger to be fired ; <float> time to firing the trigger (in seconds) Each timer will fire only once.

TRIGGER <int #1> <int #2> <int #3> <int #4> <int #5> <string #1> <string #2> <string #3> <int #6>
description: syntax: Adds a trigger field. <int #1> top-left x coordinate ; <int #2> top-left y coordinate ; <int #3> bottom-right x coordinate ; <int #4> bottomright y coordinate ; <int #5> target index reference or modifier value ; <string #1> trigger name ; <string #2> trigger string ; <string #3> link class ; <int #6> additional variable value Triggers with other field names will be ignored. Field must have both height and width to become valid. Triggers can be linked to entities, usable trigger fields and multitaps. To learn more about triggers and to view all possible trigger names, see: Creating Levels: Triggers and Using Triggers. Possible link classes:
LNK_ENTITY = entity link LNK_MTAP = multitap link LNK_TRIGGER = trigger link NONE = no link

notes:

[ 31 / 37 ]

Appendix C: Configuration variables

Configuration variables (commonly referred to as Cvars, see: CVAR) are what the name suggests; global variables registered to the engine and used to setup and adjust both system and the game. You can go and tweak these from within the script-, level-, and configuration files manually.

Setup variables
input_autoswitch input_gamepad input_guispeed input_keyleft, input_keyright, input_keydown, input_keyload, input_keyjump, input_keynext, input_keyprev, input_keypeak input_peak nosound safemode snd_dsound Toggles automatic switching into new weapons (1=on, default ; 0=off). Stored in configuration file. Toggles gamepad controls (1=on ; 0=off, default). Stored in configuration file. Mouse speed modifier as byte. Stored in configuration file. In-game keyboard configurations. Values refer to DirectInput keyboard constants. Stored in configuration file.

Switches peaking mode between toggle and hold (1=toggle ; 0=hold). Stored in configuration file. Disable all sounds (1=disable sounds). Ignores completely the sound calls so the game can be run even without sound card, like on workstation computer. Command line only. Use value 1 to revert all game settings to defaults. Command line only. Toggles DirectSound driver for sound (1=on, default ; 0=off). When DirectSound is turned off Windows Multimedia driver will be used instead. Though DirectSound is generally faster and has better compatibility, some older soundcards may have incompatible drivers, resulting stuttering playback. If so, use Windows Multimedia drivers instead. Stored in configuration file. Sound effects and music volumes in bytes (0255). Toggles player voice over (1=on, default ; 0=off). Video color depth in bits-per-pixel. Most cards dont support other than either 16 or 32 bits-perpixel. Only affects full screen mode as windowed mode uses the desktop color depth. Note that though using lower color depth results less-sharp graphics, it gives significant speed boost, especially when using low-end graphic cards. Full screen mode (1=full screen ; 0=windowed mode). Windowed mode always uses the desktop color depth for the best compatibility. Video resolution dimensions in pixels (default is 800x600). Note that TAGAP was designed for 800x600 and 800x600 only, so using higher resolutions doesn't affect graphical quality, but allows the usage of full screen with displays that don't support the game's resolution. Normally the game runs in a virtual window, but you can use vid_stretch to to stretch the screen to fit the resolution Toggles screen stretch (1=on ; 0=off). This stretches the game screen to fit the resolution instead of showing up in a virtual window. Recommended only for very fast video cards. Toggles framebuffer warping effects of water (1=on ; 0=off). Turning this option off improves performance significantly on slower systems. Toggles Cheats menu access on/off (1=on ; 0=off). Command line only. Game can't be saved and achievements can't be unlocked while cheat mode is on. Permanently hijacks another user name to be associated with the current Windows log-in name. All configurations, achievements and saved games are stored according to user name, so after changing user name you'll need to use this variable. Note that all progress made under current Windows log-in name will be lost during an account hijack. To use another account on persession basis without removing current progress, use user_name override. Command line only. Overrides user name. User name is by default the same as user's Windows log-in name (with caps replaced with _). The override user name is used for that session only; To permanently hijack an account use variable "user_hijack. Command line only.

snd_musicvol, snd_soundvol snd_voiceover vid_bpp

vid_fullscreen vid_width, vid_height

vid_stretch vid_warp user_cheats user_hijack

user_name

Editing variables
map_cannonfodder Defines cannon fodder summoning (0=off).

[ 32 / 37 ]

map_fodderrain map_fodderspeed map_interior map_nextmap map_nosave map_scheme map_sequence

Toggles fodders falling from the sky (1=on ; 2=sides and sky ; 0=off). Defines cannon fodder speed ranging from 1 to 20. Toggles use of level interior skybox backgrounds instead of full parallaxes (1=on ; 0=off). Filename of the next map loaded when the level is completed. When used from command line the next map is loaded on start-up use this to load custom levels. Toggles possibility to save on/off (1=on ; 0=off). Designed for use in sequence scripts only, but works in-game, too. Defines the default environmental theme of the level. Filename of the sequence loaded when the level is completed or proper sequence event is initiated. Use name none if you want to load the next level straight on exit. When used from command line the sequence is loaded on start-up. Title of the level. Mainly used in level scripts. Title Untitled wont be printed on loading a level. Prevents dynamically loaded graphics data from being flushed between sequences (1=on ; 0=off, default). If you want your sequence to be timed perfectly and synced with streams without falling behind on slower machines, use this. When turned on, it affects the next sequence swap and is reverted off again; You must define it for each sequence script independently. When toggled (1=on ; 0=off, default) the in-song loop points are ignored and the song is looped from the beginning to the end. Used only in sequence scripts, this value is reset back to off on every level and sequence load. When toggled (1=on ; 0=off, default) pausing the game or using the menu won't pause the music; Comes handy in sequences featuring cinematic score. This variable is reset back to off on every level and sequence load. Filename of the default song to be streamed. Use name off for no default music. When the music resumes, like after a boss fight, this is the song that'll be played. Filename of the sequence audio to be streamed. This variable is turned to off before loading a sequence, so to continue streaming current audio, you'll have to define the same stream for the follow sequence, too. Usable only in sequence scripts. Toggles entity bounding box display on/off (1=on ; 0=off). Ideal for testing collisions and offsets. Only in developer mode. Text color definitions in RGB bytes. Used in game definition script. Toggles developer mode on with value 1. Command line only. When toggled on you can access the level editor through the main menu and in-game editor shortcuts are enabled. Game can't be saved and achievements can't be unlocked while developer mode is on. Defines the game mod to be loaded. Command line only. Mods are loaded from mods directory. Toggles frames-per-second display (1=on). Amount of rendered frames-per-second will be shown at the top-right corner of the screen. Only in developer mode. Defines the entities called from within the engine. Used in game definition script. Game info and copyright string for start-up loading screen. Used in game definition script. Disables all AI making testing level geometry and trigger functions easier (1=on ; 0=off). Only in developer mode. Toggles detailed developer log output on/off (1=detailed ; 0=basic, default). While basic mode reports only the main engine events (initialization calls, errors occurred, etc.) the detailed mode also reports most file events. Detailed mode is mainly intended for bug-hunting and development. Defines the level directory for mod (default is data/script/maps). This way you can make mods that can be used in TAGAP's original maps. Used in game definition script. Enables promo screen capture mode on/off (1=disable GUIs ; 2=disable player and AI ; 0=off). When toggled on, no status display, messages or player effects will be drawn, making it easier to take environmental screenshots or capture demo reel video. Command line only. Filename definitions for sequences automatically loaded by the engine on specific events. Used in game definition script. Master volume for sound effects in percents (default is 75). Use this to tune the default balance of music and sound effects according to what kind of custom music you are using. Used in game definition script. Toggles sound engine's CPU usage display (1=on). This variable was meant for system testing and debugging during the engine development, but it also works fine to determine possible glitches created by sound overflows. Only in developer mode. Toggles whether or not the current level will be saved automatically when you launch it from the

map_title noreload

snd_noloop

snd_pausesong

snd_song snd_stream

user_bbox user_color_gui_r/g/b, user_color_text_r/g/b user_developer

user_game user_fps user_fx_spark user_info user_lobotomy user_log

user_mapdir user_promo

user_seq_start, user_seq_gameover, user_seq_newgame user_sfx_master

user_soundcpu

user_startsave

[ 33 / 37 ]

editor. Saved in configuration file. user_tex_base, user_tex_crack user_vo_ex, user_vo_neg, user_vo_pos Filename of the texture definitions for base textures used by editor and rendering engine. Used in game definition script. Voiceovers (see: VOICEOVER) for played in certain game events, like when discovering a secret area, trying to use lock without a key, etc. They are as follows; user_vo_ex is excited, user_vo_neg is negative feedback and user_vo_pos is positive feedback. Used in game definition script.

[ 34 / 37 ]

Appendix D: Essential Software

Retail software
Let's face it; You'll need to buy some software if you want to get your game done. It's simply an undeniable fact that some software suites, like Adobe Photoshop or Cakewalk Sonar, have been tuned to tiniest detail in terms of user interface, compatibility and efficiency, and though they cost some money, they'll eventually pay themselves in development speed and reliability.

Adobe Photoshop CS3

The one and only graphics software and the best 800 I've ever spent. Unequaled on every level, Adobe Photoshop has been created to answer all the needs of 2D artist of both pro and amateurs alike. You might need Photoshop 7.0 legacy file plug-ins for best Targa TGA handling, though. Note that Photoshop CS series is not to be confused with Adobe Photoshop Elements line-up, which is budget solution for photo processing and can't be used to create CGI from scratch.

www.adobe.com/photoshop

Adobe Premiere Elements

Very likely the best non-linear video editing software around. Unlike with Adobe's Photoshop, in case of Premiere I found Elements version better than the full product; Elements is slicker, faster and a lot easier to use. Besides costing around 80 it won't bankrupt you either.

www.adobe.com/premiereel

Fraps
When it came time to capture the footage for TAGAP trailer, I had two choices; Buy an expensive video capture card or go and buy beepa's Fraps for 27. Though it's best known for it's video- and screen capturing capabilities as well as it's support for Machinima community, it's also a benchmarking gadget that can come handy in game development.

www.fraps.com

Cakewalk Sonar Home Studio XL

In the beginning TAGAP's music was written as MIDI, recorded into audio tracks, hammered with wave editor, put together and encoded to Ogg Vorbis. Not-so-surprisingly we soon started looking for an alternative and Cakewalk Sonar had it all in one; Composition, arrangement, recording, encoding... heck, even web publishing!

www.cakewalk.com

Freeware software
These days it's common belief that game development is too expensive for hobbyists unless you do warez. Wrong! It's relatively cheap, as there are many freeware and/or open source tools out there. Here are the of most useful freeware programs Penguin DT used to craft TAGAP.

@Icon Sushi
Simple and effective utility for creating Windows icons. It supports anything from old 8 bit icons to 32 bit XP and hi-res Vista ones, supporting images sized from 1x1 to 256x256. @Icon also flawlessly supports wide range of modern formats.

www.towofu.net

[ 35 / 37 ]

Audacity
Free, cross-platform sound editor that simply beats the crap out of it's commercial competitors, featuring much-needed options like multi-track editing and project workspace feature. You can do a lot with it out-of-the-zip, but the ability to customize it with all the available plug-ins ensures only your imagination is the limit. Or your hard disk space.

audacity.sourceforge.net

FMOD Ex: Music & Sound Effects System

FMOD definitely deserves to get mentioned. The brilliance of FMOD lays in it's flexibility; With it you can do anything from just playing mono sample to complex hardware-supporting 3D soundscapes. On commercial front it's been used in titles like World of WarCraft and Crysis, so it's heavy league. It's free for use in freeware titles and there's also affordable hobbyist license option.

www.fmod.org

GIMP: GNU Image Manipulation Program

Though Adobe Photoshop is the definite king of 2D graphics software, GIMP has proven itself handy in smaller graphics tasks, like in creating texture patterns. It's very flexible, though requires time to get into, thanks to it's... er... funky interface. It's also available on every possible platform.

www.gimp.org

jEdit: Programmer's Text Editor

Life-saver tool and like the name says, designed for programming. It recognizes most programming language syntaxes and it's quit fast, but the best part is it's find-and-replace capability; Just type in the changes and it does it all for you, even in thousands of files. Though I like standard Notepad-alike software better, all large-scale script updating was done with jEdit. Requires Java 2 virtual machine to install and run.

www.jedit.org

Microsoft Visual C++ 2005 Express Edition

Microsoft in freeware list? Yes, as Microsoft fanboy I love surprising you skeptics! Simply put; The One-And-Only Programming Tool as free lite version. Sure, there are some features missing compared to retail editions, but nothing hobbyist can't live without. One of those very few developer tools I've ever encountered from which I have nothing bad to say. It's just perfect. Get your's NOW!

msdn.microsoft.com

NSIS: Nullsoft Scriptable Install System

Open source install system that was used to create TAGAP installer. It's from Nullsoft, developers of famous WinAmp and it's widely used. Distributing your software in installer package makes things way more user-friendly. It speaks of something that NSIS has been adapted by likes of Ubisoft, NCsoft and Google.

nsis.sourceforge.net

OggDrop
Another small utility redefining the phrase less is more. Just drag your audio files and drop 'em to OggDrop and you have the entire game soundtrack and/ or sound effects archive encoded to OGG Vorbis format in a matter of seconds. Why make it harder?

www.vorbis.com

[ 36 / 37 ]

OpenOffice.org
Open source alternative and replacement for Office suite. Though OpenOffice.org Writer requires more orientation than Word, it's more powerful, supports greater array of formats and can produce fluent .pdf and .html files. Writer was used to create all TAGAP's documentations, including this handbook you are just reading.

www.openoffice.org

Win32Pad
There are dozens of Notepad replacements out there, but I think this is the best one. It features Infinite undo, unlimited file size, yet it's light-weight and doesn't waste any extra memory. This gadget was used for both TAGAP_Script creation and website composition (yes, I'm one those dozen people who still do their websites with text editor).

www.gena01.com/win32pad

[ 37 / 37 ]