Game Information
Basic information
The current game's name can be found under the Engine namespace as a constant string.
-- Name of the current game in PascalCase.
--
string Engine.GAME
-- Returns true if user is in game (ex: not in main menu).
--
bool Engine.InGame()
-- Returns true if user paused the game (ex: score window is not open).
--
bool Engine.IsPaused()
-- Returns the name of the current game mode or an empty string if not known.
--
string Engine.GetGameMode()
-- Invoked when a new game starts with the game mode.
--
Event<string> Event.OnGameStart
-- Invoked when the game ends.
--
Event<> Event.OnGameEnd
-- Invoked when the game is paused/resumed.
--
Event<> Event.OnGamePause
Event<> Event.OnGameResume
Databases
We use the following global tables to store any constant information describing the objects and entities within the game. This information can be read and written to both by game engine itself and user scripts.
-- Maps `Entity.name` as `Entity.info` for players.
Database<CharacterInfo> CharacterDB
-- Maps `Item.name` as `Item.info` for items and `Entity.name` as `Entity.info` for single item pickups.
Database<ItemInfo> ItemDB
-- Maps `Entity.name` as `Entity.info` for projectiles, also referenced from `ItemInfo`.
Database<ProjectileInfo> ProjectileDB
-- Maps `World.GetLevelName()` as `World.GetLevel()`.
Database<LevelInfo> LevelDB
You may have noticed that these are special Database<> types as opposed a table of tables. This is because, unlike a normal Lua table, keys are always strings and values are immutable table instances.
Once the table is indexed, the table value itself can't be removed or swapped, although the contents can be cleared or changed. This ensures any reference to these table entires by value cannot be invalidated. Additionally assignment operator maps to extension by default.
Here's a quick example to clarify.
Example/index.ts
ItemDB["Test"].a = 4; // Table automatically created.
const tbl = ItemDB["Test"];
ItemDB["Test"] = { b: 5 } as any; // { a = 4, b = 5, ... }
delete ItemDB["Test"]; // {}
print(tbl == ItemDB["Test"]); // "true", still the same table.
The default fields we expect below will perform the following transformations for compatibility with JSON assignments:
- If assignment is in form
Database[Id] = Value,Value.idwill be automatically inserted. - If the expected type is an enum, the string representation will be automatically converted.
- If the expected type is a vector, the table representation either as
{ x=4, y=4 }or{ 4, 4 }will be automatically converted. - If the field within the structure maps to another Database with an
idfield, its assignment will be done automatically.
In case you wish to fill the database entries lazily as the information is needed, you can also register a hook using the call syntax. The hook will only be invoked when the key was not already in the database. Errors during the execution of this hook are handled similary to events and return value will be ignored unless it's a table. The mandatory id field will be automatically set.
Example/index.ts
ItemDB((key) => {
if (key == "Test") {
return { c: "TestTest" };
}
});
const info = ItemDB["Test"];
print(info.id, info.c); // "Test TestTest"
Effects
Effects are the way we represent any consequences to the game world or the players; from spawning a giant bear, to a projectile that heals allies, effects allow a lot of versatility. They are not constructed directly but instead via creation of a projectile wrapping them.
-- Effect type.
--
EffectType EffectInfo.type -- Default: GENERIC.
-- Range of the applied damage.
-- - If damage is negative, it is a heal.
-- - If minimum damage is not set, damage does not scale.
--
float? EffectInfo.damage
float? EffectInfo.minimumDamage
-- Scaling by bone type.
--
float EffectInfo.headshotScale -- Default: 2
float EffectInfo.limbScale -- Default: 0.5
-- Percentage of health returned to the owner on damage.
--
float EffectInfo.lifesteal -- Default: 0.
-- Inner and outer radius for AoE effects.
-- - If outer is not set, effect is not AoE.
-- - If inner is not set, effect does not scale.
float? EffectInfo.innerRadius
float? EffectInfo.outerRadius
-- If AoE, ranges of the cone the damage is applied to.
-- - Values must be normalized to [0, 2pi], begin < end.
-- - If not set, its a full circle.
float? EffectInfo.angleBegin
float? EffectInfo.angleEnd
-- Durations for the delay, expiry and tick.
--
float? EffectInfo.delayDuration -- ex: Grenade explosion delay.
float? EffectInfo.expiryDuration -- ex: Smoke grenade duration.
float? EffectInfo.tickDuration -- ex: Molotov damage ticks.
-- Auxiliary value for the specific type of special effect.
--
float? EffectInfo.value
-- Filter for the health type.
--
bool EffectInfo.appliesToHealth -- Default: true.
bool EffectInfo.appliesToArmor -- Default: true.
bool EffectInfo.appliesToShield -- Default: true.
bool EffectInfo.appliesToBarrier -- Default: true.
-- Set if damage scales by the given measurement.
--
bool EffectInfo.scalesByDistance -- Default: false.
bool EffectInfo.scalesByCharge -- Default: false.
bool EffectInfo.scalesByBone -- Default: false.
-- Target filter.
--
TargetFilter EffectInfo.filter -- Default: ANY.
Projectiles
Projectiles wrap an effect and describes how they are launched when an action is triggered, however despite the name, the instance might not be a projectile but can also represent melee attacks, self-buffs and hit-scan bullets.
-- Identifier of the projectile, can be null if anonymous.
string ProjectileInfo.id
-- Applied effect on trigger.
--
EffectInfo? ProjectileInfo.effect
-- Positional and angular offsets from the launching entity.
--
vec3 ProjectileInfo.locationOffset -- Default: vec3(0,0,0).
vec3 ProjectileInfo.rotationOffset -- Default: vec3(0,0,0).
-- Maximum travel distance.
--
float ProjectileInfo.maxTravelDistance -- Default: math.huge.
-- Initial and minimum/maximum speeds.
--
float ProjectileInfo.initialSpeed -- Default: math.huge.
float ProjectileInfo.minimumSpeed -- Default: 0.
float ProjectileInfo.maximumSpeed -- Default: math.huge.
-- Acceleration and gravity coefficient.
--
float ProjectileInfo.acceleration -- Default: 0.
float ProjectileInfo.gravityCoeff -- Default: 0.
-- True if speed scales by charge.
--
bool ProjectileInfo.speedScalesByCharge -- Default: false.
-- True if gravity scales by level gravity.
--
bool ProjectileInfo.gravityScalesByLevelGravity -- Default: false.
-- Collision filter, radius and bounciness.
--
TargetFilter ProjectileInfo.collisionFilter -- Default: ANY.
float? ProjectileInfo.collisionRadius
float? ProjectileInfo.bounciness
-- True if dummy projectile, effect is immediately applied at original location (ex: Melee).
--
bool ProjectileInfo.isDummy -- Default: false.
-- True if homing/sticky projectile.
--
bool ProjectileInfo.isHoming -- Default: false.
bool ProjectileInfo.isSticky -- Default: false.
Actions
Actions represent discrete uses of an item specified by the user input, for instance: a weapon with different primary and secondary fire types.
-- Delay in launch after cast.
-- If charagable, charge duration, else animation time.
--
float ActionInfo.delay -- Default: 0.
-- Cooldown time per use.
--
float ActionInfo.cooldownTime -- Default: 0.
-- Ammo/Mana requirement for using.
--
float ActionInfo.ammoCost -- Default: 1.
float ActionInfo.manaCost -- Default: 0.
-- Casting mode.
--
CastingMode ActionInfo.castingMode -- Default: CAMERA.
-- Support for cancelling / charging.
--
bool ActionInfo.cancellable -- Default: false.
bool ActionInfo.chargable -- Default: false.
-- Firing mode override.
--
FiringMode? ActionInfo.firingModeOverride
-- Number of projectiles fired if firing mode is burst.
--
uint ActionInfo.burstCount -- Default: 1
-- Interval between bursted projectiles.
--
float ActionInfo.burstInterval -- Default: 0
-- Firing interval.
--
float? ActionInfo.firingInterval
-- List of projectiles launched on cast.
--
ProjectileInfo[] ActionInfo.projectiles -- Default: {}.
Items
Wrapping all the actions, projectiles and effects, item descriptors can be used to represent abilities, weapons, health pickups, valuables and many more.
-- Identifier of the item.
--
string ItemInfo.id
-- Display name and the Texture ID representing the item.
--
string? ItemInfo.displayName
int ItemInfo.icon -- Default: NULL_TEXTURE
int ItemInfo.maskIcon -- Default: NULL_TEXTURE
float ItemInfo.iconAspect -- Default: 1
-- Type of the item.
--
ItemType ItemInfo.type -- Default: GENERIC
ItemSubType? ItemInfo.subtype
-- Ammunition kind for filtering for suitable ammo packs.
--
string? ItemInfo.ammoKind
-- Weapon group for filtering for suitable attachments.
--
string? ItemInfo.attachmentGroup
-- Ammo regenration time if relevant.
--
float? ItemInfo.ammoRegenTime
-- Maximum ammo that can be held by the weapon.
--
uint? ItemInfo.maxAmmo
-- Item grade / quality, if health/armor/shield/barrier/mana pickup the value gained by use.
--
int? ItemInfo.grade
-- Item weight and speed coefficient.
--
float? ItemInfo.weight
float ItemInfo.weightSpeedCoeff -- Default: 1.0
-- Optional item states.
--
bool ItemInfo.hasZoomState -- Default: false
bool ItemInfo.hasDynamicZeroingDistance -- Default: false
-- Actions.
--
ActionInfo[] ItemInfo.actions
Character information
Character information describes a specific hero or champion in the game.
-- Identifier of the character.
--
string CharacterInfo.id
-- Display name and the Texture ID representing the character.
--
string? CharacterInfo.displayName
int CharacterInfo.icon -- Default: NULL_TEXTURE
float CharacterInfo.iconAspect -- Default: 1
-- Default abilities to be used instead as the primary attack in place of the current weapon when available.
--
string[] CharacterInfo.defaultAttackSpells -- Default: string[]
Level information
Level information describes a specific map in the game.
-- Identifier and display name of the level.
--
string LevelInfo.id
string? LevelInfo.displayName
-- Minimap texture representing the level.
--
int LevelInfo.minimapTexture -- Default: NULL_TEXTURE
float LevelInfo.minimapAspect -- Default: 1
-- Boundaries of the level.
--
vec3? LevelInfo.minPos
vec3? LevelInfo.maxPos
Appendix
Here's a list of enumerations previously mentioned but not declared to keep the snippets short.
-- Target filters.
--
TargetFilter TargetFilter.ANY -- No filter.
TargetFilter TargetFilter.ENEMY -- Only enemies of the owner.
TargetFilter TargetFilter.ALLY -- Only allies of the owner.
TargetFilter TargetFilter.PLAYER -- Only players.
TargetFilter TargetFilter.NON_PLAYER -- Only non-players.
TargetFilter TargetFilter.SELF -- Only owner itself.
TargetFilter TargetFilter.NONE -- No targets.
string TargetFilter.ToString(TargetFilter value)
-- Effect types.
--
EffectType Effect.GENERIC -- No special effects, only damage/heal if relevant.
EffectType Effect.BLIND -- Blinds the targets.
EffectType Effect.SMOKE -- Blocks the visibility in the radius.
EffectType Effect.SILENCE -- Silences the targets.
EffectType Effect.STUN -- Stuns the targets.
EffectType Effect.MOTION -- Pushes the targets away or towards the impact location, `EffectInfo.value` contains the velocity (>0 for towards).
EffectType Effect.INVISIBILITY -- Makes the targets invisible.
EffectType Effect.ENTITY_SPAWN -- Spawns a pet or a trap at the impact location.
string Effect.ToString(EffectType value)
-- Casting modes.
--
CastingMode CastingMode.CAMERA -- Cast towards view angles, Item:cast
CastingMode CastingMode.DIRECTIONAL -- Cast towards a position, Item:castAt
CastingMode CastingMode.TARGETED -- Cast at a specific target, Item:castOn
string CastingMode.ToString(CastingMode value)
-- Item types.
--
ItemType Item.GENERIC
ItemType Item.WEAPON
ItemType Item.ATTACHMENT
ItemType Item.AMMO
ItemType Item.ABILITY
ItemType Item.HEALTH
ItemType Item.ARMOR
ItemType Item.SHIELD
ItemType Item.BARRIER
ItemType Item.MANA
ItemType Item.VALUABLE
ItemType Item.MATERIAL
ItemType Item.TOOL
string Item.ToString(ItemType value)
-- Item subtypes.
--
ItemSubType ItemSub.WEAPON_RIFLE
ItemSubType ItemSub.WEAPON_AUTO_RIFLE
ItemSubType ItemSub.WEAPON_PISTOL
ItemSubType ItemSub.WEAPON_CROSSBOW
ItemSubType ItemSub.WEAPON_SHOTGUN
ItemSubType ItemSub.WEAPON_SNIPER
ItemSubType ItemSub.WEAPON_ROCKET_LAUNCHER
ItemSubType ItemSub.WEAPON_GRENADE
ItemSubType ItemSub.WEAPON_GRENADE_LAUNCHER
ItemSubType ItemSub.WEAPON_BEAM
ItemSubType ItemSub.WEAPON_MELEE
ItemSubType ItemSub.ATTACHMENT_RED_DOT
ItemSubType ItemSub.ATTACHMENT_HOLOGRAPHIC
ItemSubType ItemSub.ATTACHMENT_SCOPE
ItemSubType ItemSub.ATTACHMENT_LASER
ItemSubType ItemSub.ATTACHMENT_FLASH
ItemSubType ItemSub.ATTACHMENT_SUPPRESSOR
ItemSubType ItemSub.ATTACHMENT_COMPENSATOR
ItemSubType ItemSub.ATTACHMENT_FLASH_HIDER
ItemSubType ItemSub.ATTACHMENT_CHOKE
ItemSubType ItemSub.ATTACHMENT_MAGAZINE
ItemSubType ItemSub.ATTACHMENT_GRIP
ItemSubType ItemSub.ATTACHMENT_STOCK
string ItemSub.ToString(ItemSubType value)