canonical link to CPACK - where to get the author-maintained version

This is the documentation page for the first person game mode. Information for players can be found here.

The FPS scripts were made with extensibility and versatility in mind, but because of that some parts of them may seem a little daunting. This page's goal is to act as a guide and a reference to hopefully lower that barrier to making your own first person levels.

As a general rule, all weapon and attribute names must follow the same capitalization rules when used as inputs, no matter what script they appear in. Weapon names are all lowercase (“cannon”) and attribute names are capitalized and camel cased (“MaxRange”).

Until the sniper is fully integrated into the existing weapon system, its attributes are included purely for completeness' sake. It breaks many of the rules stated for other weapons, and cannot be easily modified with scripting.

Almost all weapon attributes have the same effect on all weapons. This holds true even if that weapon doesn't normally have that attribute. For instance, in “FPS: Anti Up” (map #586), the cannon is given AC simply by having an item upgrade give the cannon anticreep-related attributes.

Attributes that do not end in a “.0” are integers (they ignore anything past the decimal place when finding their effect).

• DPS Monitor
• Wall Tool
• InfoCache Controller

This script controls all aspects of first-person movement: speed, collision, respawn, etc. “Run when paused” should be turned on, so it can return normal controls if the player leaves free view while paused.

Script vars:

• MoveSpeed: The maximum speed the player can hit, in cells per update. High values will lead to clipping.
• AllowMoveOnVoid: Whether void is counted as an impassable wall, or terrain height 0. Values other than 0 allow movement on void. Only really makes sense to allow it if the level has a planet.
• CollisionThreshold: The highest terrain difference that the player can walk over.
• StartX, StartZ: The cell coordinates of the player's spawn and respawn point.
• StartRotation: The direction that the player points when they spawn, in degrees. 0 faces them in the positive Z direction.

Contains logic for health and firing weapons.

Script vars:

• MaxHealth: The max health the player has. 30 is the default. Damage taken is proportional to the square root of creeper, with a depth of 1 dealing 0.1 damage per update.
• BonusRequirement: The percentage of health the player must stay above for the custom objective.
• StartingWeapons: A string containing a list of the weapons that are unlocked upon starting the level, separated by commas.

Makes all totems charge in a way usable in a first-person level. Rules are as follows:

• Totems will gain charge at an increasing rate while the player is within 15 cells.
• Partially charged totems will stop charging when the player is outside that radius, but will not lose charge.
• Totems will lose charge when there is creeper on the center cell of the unit.
• Disabled totems (“unit: off”) will not charge, and any existing ammo will be removed.

There are no script vars.

Determines the starting settings for all weapons.

All script vars except for those ending in “other” just set the starting value for the weapon and attribute in the name. See weapon attributes for a more detailed description.

Script vars ending in “other” are for setting attributes that are not already listed for a particular weapon. The string is case sensitive, and must be formatted as a list of attribute-value pairs. The weapon name should not be added to the attribute name. An example would be:

DmgDepth: 0.5, DmgDist: 5, Rate: 10

Note that each key-value pair is separated with a colon, and different pairs are separated by commas. Whitespace is ignored.

This section requires knowledge of 4RPL.

Certain parts of the game mode are stored as global variables, allowing them to be read from any script in the level. They are listed below.

Various parts of the game are communicated via messages. Registering other scripts for these messages can sometimes be useful.

The weaponAttributes table has an entry for each weapon, accessible by its name. That value is another table with entries for all of that weapon's attributes. This means that the simplest syntax for reading the value of a weapon's attribute is:

<-*weaponAttributes {"weaponName"} {"attributeName"}

Although if many attributes need to be read for the same weapon, it can be easier to store the second table to its own (local) variable.

Similarly, the simplest way to change a weapon's attribute is:

value ->*weaponAttributes {"weaponName"} {"attributeName"}

To put everything together, here is an example that uses everything mentioned so far.

Whenever a bullet creates its weapon effect, it sends a message on the “WeaponEffect” channel. _DATA will be a list with two elements: the first is the name of the weapon, and the second is a 3-dimensional vector of the location where the weapon effect was made. By registering a script for that event, custom effects can be added to weapons without modifying the original scripts.

The base template for this is as follows:

once
    RegisterForMsg("WeaponEffect" "DoCustomWeaponEffects")
endonce

:DoCustomWeaponEffects
    #Store data into more readable vars
    <-_DATA[0] ->weapon
    <-_DATA[1] ->effectPosition
    
    #Read whatever attributes are needed for this effect
    #Repeat if necessary
    <-*weaponAttributes {<-weapon} {"SomeAttribute"} ->someAttribute
    
    #Then create the effect. Teleport the player, flip C/AC, damp waves, whatever you want.

The weapon loader and item scripts don't filter what stats are being added to the weapon, so new attributes can be added and read just like the base ones.

⇐ Index