Map scripting is the use of the building blocks (entities) of logic in the map to create effects, objectives, game logic flow, etc. You can use map scripting to create complex scenarios (single and multiplayer). Some map script entities are not multiplayer-safe. Some are pure server-side but their effects are seen on the clients.

You do not need to be a programmer to use map scripting, because its more like connecting blocks together than actually writing code.

All map scripting is done visually with no code actually needing to be written. Instead, you place the script entities into the map like you would any other entity (such as player start point), and then open the script pairs window (windows->Script pairs) and alter the values in there to hook things up to each other.

Examples of when you need to use map scripting

• Any time you need some sort of an objective for a team to complete
• Any time you want to use the 'assault' system (where teams switch sides after one team is successful, to have the other team attempt to beat their time)
• Any time you want some dialogue to appear, or anything besides normal deathmatch gameplay to occur

Map Script Basics

There is no actual 'scripting' language in map script. Instead, entities are placed in maps, and then linked together like wiring a circuit, to produce the final effect. There are three types of script entities in Hyperbol: Sensors, Logic Components, and Actions. These enties are linked to each other by commands and targets. These can be thought of as the wiring between them. When a script entity 'activates' its target, it sends the target script entity a command of your choosing. For example, a sensor might send a "player start" entity a "disable" command. This would cause the player start to no longer be available to start at.

Sensors

A sensor is a script entity that starts the whole thing. Without a sensor, generally nothing interesting would ever happen. For example you can put a radius sensor in the map. This sensor would activate whenever something meeting your specified criteria passed within the specified radius of the sensor. So it senses things nearby. There are many types of sensors. Some entities have a sense component and also an action component to them, as they can chain react.

Nothing happens unless a sensor triggers it. So somewhere along the chain there has to be a sensor to get the ball rolling. Some entities are sensors themselves - for example, the 'destroyable props' like the core in mining facility is a sensor, because it activates when it is destroyed, allowing it to start stuff happening when it explodes. The most used sensors are:

• Destroyable Prop Objects - These are things like the surface beacons, the core in mining facility, and so on. These can start things happening when they are repaired, destroyed, captured, lost, etc. These are pretty much the #1 source of any script in any objective map.
• "No chance to survive" sensors - These sense when a team has been completely defeated. Once this happens, they will start their targets. These targets are usualy 'game over' type scripts.
• "Game time" sensors - these can sense when time has run out.

Logic Components

Logic Components are generally like filters. They don't do anything themselves, but they do logic instead. For example, a Counter. Whenever a counter is activated by something (perhaps a radius sensor), it increments its count. The counter will only activate its own target(s) when the count reaches a specified amount. This lets you count things such as destroyed buildings, time in areas, etc. Even though its activated, it does not activate its own targets until the count it's looking for is reached, thus acting like a filter

The most common logic component (and often the only one used) is the multiplexer. A multiplexer, once it is activated by a sensor of some kind, will in turn, activate all its own targets. It can target up to four different other entities, and can delay between each. It is therefore used for things like cinematics. Multiplexers can be chained - so for example, you can have a series of multiplexers, each activating three other scripts, moving the camera around for example, and then the fourth one is simply the next multiplexer in the chain.

Actions

Actions are actual things that the game does.

For example, an 'entity spawner' will create entities of your choosing when activated. So if you choose for it to expel time bombs, then whenever it is activated, it will expel a time bomb.

You could make a trap system, for example, by hooking a radius sensor up to a plasma bolt entity spawner, aimed towards the sensor. Then any ship touching the sensor would have a plasma bolt expelled towards it. There are also actions which end the game, restart the map, show special effects, move the camera around, and pop up "story mode" dialog boxes to the player. A lot of actions are meant for tutorial/single player and will not work well in multiplayer. For example, disabling parts of the GUI would not be something that works Multiplayer, but some scripts have been specifically designed for multiplayer. Most of the cinematics, such as screen fades, camera movements, etc, do work. Most of the dialog boxes that pop up for story/tutorial mode do not.

The most common actions are

• Assault Mode - This action takes care of resetting the game and switching teams and so on, in an assault game. When activated for the first time, it switches everyone around and restarts the map. Its a special action because when activated for a second time, it will act like a Logic component instead, and activate a script of your choosing depending on who won or lost.
• Special Effect Spawner - makes explosions and things
• End Game - Ends the match, awarding victory to a team. This is used often in response to an assault mode script.
• Camera / Cinematic scripts which move the camera around or fade in and out.

Others

There are other miscelaneous script entities, but those generally perform dual functions or simply are a certain projectile or deployed object. The "Destroyable Prop Object" is the most popular of those. This object shows up as a model of your choosing, and is destroyable or capturable by a team of your choosing. When destroyed, it plays effects of your choosing and changes its model to another destoyed model. It also activates its targets when it is repaired, dies, or any other state change, so it acts as both an action and as a sensor. Its one of the most useful objects in the game. Scripted turrets are in this same category and can have the same triggers.

Important Script Pair Fields

The most important type of field for map scripting is the targetname, command, and target fields. The map editor has a large amount of help built into it for every type of script entity. You can see this help whenever you choose a field or a script entity, in the window below the entity chooser, or in the script pairs window.

targetname

The targetname of an entity is its actual 'name' in the scripting engine. Anytime you need to refer to that entity by another entity, you use its target name. So for example if you fill in 'joe' as the targetname of an effects spawner, then any other sensor entity that needs to activate that effect spawner, would use the word 'joe' in the various fields that need to refer to it. Its essentially a label for the entity so that it can be referred to by other entities.

Note that many entities can have the SAME targetname. You can make many effects spawners all called 'joe'. This is a good timesaver.

targets

Sensors and other things have targets. For example, a Destroyable Prop object (like the core in mining facility) has a 'DestroyedTarget', a 'RepairedTarget' and many others. A radius sensor just has a 'Target'. A multiplexer has many targets, like Target1, Target2, Target3, Target4. All of these fields are expecting you to fill in a targetname of an entity. So in the previous example, suppose you filled in 'joe' as the targetname for an effect spawner. That effect spawner's 'targetname' is now Joe. It is how you refer to it in all other entity target fields. So if you fill in 'Joe' in the Destroyable Prop Objects 'DestroyedTarget' field, then that effect spawner would activate whenever the prop is destroyed. Because you can have many entities with the same targetname, this means if you have not just one, but MANY effects spawners all called 'joe', they will ALL activate when 'Joe' is targetted.

Commands

Generally, for each 'target' field, there is a 'command' field. For example, the multiplexer has Target1, Target2, Target3, Target4. It also has Command1, Command2, Command3, Command4. Usualy this command is 'activate' and you can generally leave it that way. Its basically a short command that the target gets fed when it is activated. So if you target that effects spawner in the previous example, by using 'Joe' as the target, but you change the command field from 'activate' to 'hooray', then all of the entities with the targetname of joe will be told to 'hooray' instead of 'activate'. This can be very useful because there are entities which listen for specific commands. you can see the commands they respond to by viewing them in the 'create entity' window. It lists the commands for the entity you're about to create. Examples of often used commands

• enable 0 - Used to tell a Player Start Point to belong to the green team
• Enable 1 - Used to tell a Player Start Point to belong to the orange team
• Enable -1 - Used to tell a Player Start Point that it belongs to nobody
• activate - generally makes a script do its thing
• disable - stops a sensor from working until you call enable or activate on it again
• enable - starts a sensor again
• healable nnn - switches the ownership of a Destroyable Prop object to team nn (0 or 1 please)

Example

So for example, lets make an effect show up whenever someone enters a particular radius. First, create or load a map that has walls/arena/starts/etc. that we can use to practice. 1. Add a "radius sensor" to your map (use the entity browser)

1. Add an "Effect Spawner" to your map (use the entity browser)
2. Open the Script Pairs window and select the Effect spawner

3. Change the TargetName of the Effect Spawner to "effectspawner1". This means that other entities which need to link to this one, will use that phrase to refer to it.

4. Alter the other fields of the Effect Spawner as appropriate: Change the Effect to 0. Change the EffectParms1 to "32.0 0.0 0.0". Note what the help below the script pairs window says about these fields. Leave the other fields zeroed as default has. This all means that when activated, the effect spawner will create a shockwave effect with radius 32.

5. Select the Radius Sensor.
6. Since we dont need anything to target the sensor, we leave its targetname blank. Targetname is for when you need to target this entity by another one.
7. We want the radius sensor to target the effect spawner. so we change the "Target" field to "effectspawner1" - the same as the targetname of the effects spawner
8. Turn 'script mode' on and move closer to see the two entities, with the camera. Script mode is a checkbox in the top bar. If you got the name and targetname correct, it should actually show the link between the two entities as a stretched arrow
9. Leave the "Command" field as "activate". Note that this is the command that is fed to the target. Some entities take all sorts of commands like "Deactivate" or "activate" or "changeowner 12" etc. When you select the entity in the entity browser, its commands are shown.

10. Set "StartsOn" to true, so the radius sensor does not need to be activated - it starts out sensing immediately

11. Set "Radius" to a value like 128.0 . This is how big an area the radius sensor is to sense in.
12. Leave Frequency to 100. Since there are 100 ticks a second, this means that it 'senses' every second. Setting this too low can severely impact game performance.

So now you have a radius Sensor that is targetting the effect spawner Action. Now whenever a player is in this radius, the effect will spawn every second. You could get quite complex here. Here are some other things you could do with this setup.

• Activate a multiplexer entity instead of directly activating the effect directly. A multiplexer is like a sequencer. It can activate a series of things in sequence. Then once the multiplexer is activated, wire the multiplexer up to turn the radius sensor off for a few seconds. You can do this by making the multiplexer target the sensor and feeding it the "disable" command. Then feeding it the "activate" command after a few seconds have passed. You could trigger cinematics/etc with the multiplexer.
  • Most game logic involves multiplexers to sequence things.
  • Generally, a sensor will activate a multiplexer, then the multiplexer will trigger a cascade of effects/actions/etc, such as showing effects, destroying things, moving camera around, and showing dialogue to the player.

• Once everything is linked up, you can copy and paste the effect spawner as many times as you like. Since they will all have the same targetname, they will all be activated whenever the radius sensor fires.

• You can also create other action entities such as entity spawners, and give those the same targetname ("effectspawner1"). They will also activate since they have the same targetname. If the map editor is in script mode you can tell the linkages between objects.

Entity Names

Some actions and sensors require entity names. For example, the entity spawner needs entity names to fire out, and the radius sensor needs entity names to filter (if you want to filter). Here are some entity names to start with (more are coming)

• ENTCLASS_PROJ_BASICBOMB - Plasma Bolt
• ENTCLASS_PROJ_BASICBOMB2 - Plasma Bolt - Upgraded
• ENTCLASS_PROJ_HYPERBOL - Hyperbol
• ENTCLASS_PROJ_HYPERBOL2 - Upgraded Hyperbol.
• ENTCLASS_BUILD_LAUNCHPAD - The player ships. You can use this in filters to restrict sensing only to player ships and not, for example, anything which enters the area (recommended!)
• ENTCLASS_PROJ_DISRUPTOR - Disruptor. Also disruptor2 is available.

Other Important Entities

• Jason Head - This is the 'face' to the players. It shows dialog, can play a speech wave file, and is basically the way dialogue is represented. For example, you supply it with a set of images to display, and a sound file to play, and text to show, and it presents it as if the speech and dialog is being presented by that person. This can be used to write story mode campaigns.
• Destroyable Prop Object - An object that can be destroyed. Generally used as objectives in objective based games. This could also just be random destroyable scenery. anytime you need something to be capturable by parking nearby, or destroyable, this is what you use. It has a vast amount of configurable items
• Force Wall - Similar to the Destoyable Prop Object, except it is a force field that stretches from the Start Point to the End Point.
• Assault Mode - This is the basic building block of an assault mode game. The first time it is activated, it simply resets the game and switches sides for everyone. The second time it is activated, it can fire specific targets, depending on the command used to activate it. generally, each team gets one of these.
• Cinematics Screen - This script must be activated before any other cinematic scripts can be activated. It ensures that the player cannot move the camera around on their own, and shows the top and bottom masking on the screen. Use "Activate" and "disable" on it. It also automatically clears off if the assault script fires, or the game ends.
• Objective - Basic building block for objective-based maps. These can be assigned text of your choosing, and a team of your choosing. They show up on the objectives panel. Players can click them on that panel to move their camera to the position of the objective in the game world.
• Object State Checker - Used to check the state of a "Destroyable Prop Object". You can use this to filter. For example if you want to do something only when all 3 of a certain type of destroyable are dead, then whenever any one of them dies, you'd activate an Object State Checker that targets the three destroyables. The Object State Checker only fires its targets if all checks succeed.
• Player Start - Players start here. You can feed it command "enable (number)". the number is a team mask. 0 is nobody. 1 is team 1. 2 is team 2. 3 is both teams! 65535 is absolutely everyone (this value is ignored in non teamplay). This is often used in objective games when a surface beacon (which is just a destroyable prop object) is captured by a particular team. When that happens, the beacon fires its Object State checkers. They check to see who owns the beacon. They award ownership of the player start as appropriate.

Important Models for Props and Destroyables

Destroyable objects and Props take one of the following as their models. note that it takes the full path, so for sky_nexus, you'd use data/models/sky_nexus/sky_nexus.vm2 and mexfile data/models/sky_nexus/sky_nexus.mex

• Prop - sky_nexus
• Prop - sky_ribbon
• Prop - sky_ring
• Prop - sky_asteroids
• Prop - sky_hyperchan1
• Prop - sky_hyperchan2
• Prop - prop_ccenter
• Destroyable - prop_ctrlstation_big , prop_ctrlstation_big_destroyed
• Destroyable - prop_ctrlstation_small, prop_ctrlstation_small_destroyed
• Destroyable - prop_dome1, prop_dome1_destroyed
• Destroyable- prop_energycore, prop_energycore_destroyed
• Turret (Red, special) prop_turret2_red, prop_turret1_red