User Tools
This is an old revision of the document!
Table of Contents
⇐ Index
qople - First Person Tools
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.
Basic Conventions
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.
Weapon Attributes
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).
| Attribute Name | Default Value | Description | Notes |
|---|---|---|---|
| Rate | 30 | The number of updates between shots. Values of 1 and below max the weapon fire rate, at once per update. | |
| DmgDepth | 0.0 | The depth of normal damage to creeper. Is affected by crimson (20% damage). | The same as the MaxNumCells, Radius, and Amt arguments to the DamageCreeper function. |
| DmgDist | 0 | The maximum radius that normal damage will damage creeper at. | |
| DmgMaxCells | 9999 | The maximum number of cells that normal creeper damage can affect. | |
| DmgIterations | 1 | Increases normal damage spread against thin creep, decreasing damage loss. Multiplies the max cells when creeper is less than DmgDepth deep. | Implementation is to spread damage across several DamageCreeper calls with decreased amounts. |
| ProjSpeed | 10 | How fast the weapon's projectiles travel, in cells per update. | |
| MinRange | 0 | The lower bound of the mortar's targeting, in cells. | Mortar only. |
| MaxRange | 100 | The upper bound of the mortar and sniper's targeting, in cells. | Mortar and sniper only. |
| AcDepth | 0.0 | The depth of AC deposited per shot. | Same as the Amt, Range and Cap arguments to the AddCreeperWithCapInRange function. |
| AcDist | 0 | The radius that AC is deposited inside of. | |
| AcCap | 0.0 | The maximum depth that AC can be deposited to. Keeping the cap at 0 will add AC damage without creating AC, effectively giving bonus damage against crimson. | |
| UnitDmgAmt | 0.0 | The amount of damage dealt to vulnerable enemy units. Most units have a max HP of 1. | |
| UnitDmgDist | 0.0 | The radius inside of which vulnerable enemy units will be damaged. | |
| AimAssist | 0.0 | The maximum angle from the center of the screen that the sniper will lock onto a target. | Sniper only. |
| NetMult | 0.0 | Keeps track of the total strength of upgrades the weapon has received. Should not be modified without upgrading the weapon accordingly. Info cache-based upgrades increment this automatically, so only custom upgrades should interact with it. |
List of Units (CMODS) in this CPACK
4RPL Extensions
This section requires knowledge of 4RPL.
Global Variables
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.
| Variable Name | Description |
|---|---|
| playerPos | The position of the player, as a 3-dimensional vector. It is the location of the camera when the player is in first person mode, not the terrain below the camera. This means it is roughly 9 cells above the terrain. Changing this will teleport the player to that x and z, but the y always follows the terrain. |
| playerForward | A normalized 3 dimensional vector pointing in the direction the player is looking. Changing this will not rotate the player, since camera rotation is handled by the free view mode, not a script. Useful for making something move in front of the player. |
| playerHealth | A floating point from 0 to 1 representing how much health the player has out of their max health. |
| weaponAttributes | A table containing all attribute values for all weapons. More detail in interacting with weapon attributes |
Messages
Various parts of the game are communicated via messages. Registering other scripts for these messages can sometimes be useful.
| Message Channel | When it is sent | Data included |
|---|---|---|
| ItemCollected | When an info cache is collected via the item.4rpl script | The ID of the unit that sent the message |
| PlayerDied | When the player's health reaches 0 | How many times the player has died |
| Respawn | When the respawn button is pressed | 0 |
| WeaponEffect | When a bullet is destroyed and creates weapon effects | A list: [“weaponName”, position (a V3)] |
Interacting with Weapon Attributes
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"}
Adding Custom Attributes
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
