Projectiles (combat.projectiles) #

What it is for #

combat.projectiles flies point projectiles, straight or ballistic, in a bounded pool. launch returns an id; each tick the kit sweeps every segment of the path through the physics port, the owner excluded. A contact ends the flight once and deals the damage through combat.damage when combat.health knows the target, through vehicle.damage for a vehicle, otherwise through its health component. projectile.impact announces every contact, scenery included. A finished shot stays in the snapshot for its trail and impact. Each shot can carry its own look and behaviours: homing, bounces, splash damage, chain jumps, an on-hit status, a mine, a returning throw. combat.ranged delegates to it when its projectile option is on. The presentation draws the shots in flight, world-space trails, impacts and the light they carry.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "combat.projectiles" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "combat.projectiles",
                              config: { "speed": 12, "gravity": 0, "damage": 25, "style": "fire" } }

It requires physics.port and game.engine; the damage path uses combat.core when installed.

First example #

<!-- test: kits/game_engine/host/tests/projectile_return.rs::manual_rest_recall_one_damage_and_restore_follow_the_same_real_sweep --> A returning throw in manual mode (Rust kit host, with a physics port). The owner launches a shot toward a foe 4 m ahead; it passes through the foe once (15 damage), rests at its range of 8 m, and a recall by the owner sends it back, where it is caught. Another entity cannot recall it, and the foe is damaged only once for the whole throw.

{ "service": "combat.projectiles", "method": "launch", "args": [{
    "owner": "e1", "origin": [0, 1, 0.4], "direction": [0, 0, 1],
    "speed": 12, "damage": 15, "lifetime": 20,
    "return": { "mode": "manual", "range": 8, "catch": 0.8 } }] }
{ "service": "combat.projectiles", "method": "recall", "args": ["e1"] }

launch answers the shot id (or null when refused or the pool is full); recall answers the number of shots recalled.

Settings and defaults #

All except presentationProfile are moddable.

Services, events, variables #

• Service combat.projectiles: launch({ owner, origin, direction, speed?, gravity?, lifetime?, damage?, source?, look?, homing?, bounces?, bounceOn?, restitution?, splash?, chain?, status?, return?, mine? }), snapshot() and recall(owner, id?) (Rust, manual returns).
• Behaviours of a launch: look { style, variant, color, radius }; homing { turnRate, range?, target? }; bounces (0 to 8), bounceOn (scenery or all) and restitution; splash { radius, share?, onExpire? }; chain { targets, radius, share?, speed? }; status { id, stacks? }; mine { arm?, trigger? }; return { range?, catch?, mode? } (auto or manual; manual cannot combine with homing, bounces or mine).
• Events projectile.launched, projectile.impact (target, damage, applied, bounced), projectile.chained, projectile.splashed, projectile.planted, projectile.detonated, projectile.returning, projectile.returned, projectile.rested, projectile.expired, projectile.ended (reason returned, expired, hit, owner-dead or owner-lost), and the compatible combat.hit.
• Variable combat.projectiles.active.
• Script verbs projectile.launch { instance | owner, origin?, direction?, ... } and projectile.recall { instance | owner, id? }.

Hooks and modding #

Engines #

Web and the native player (Rust). The manual return, recall and aimFromView of the launch verb are Rust only.

When it does not do what you expect #

• launch answers null: the owner is unknown, the pool is full (maxActive) or projectile.launch was cancelled.
• No damage: the shot hit scenery, expired (lifetime), or the target is unknown to combat.health; read projectile.impact.
• The shot passes through its owner: by design, the owner is never hit.

Limits #

No area query beyond splash and chain. A manual returning shot keeps at most 16 victims in its ledger and cannot also home, bounce or be a mine.

Versions #

Kit 1.8.0 (Rust direct contacts go through the shared defense of combat.defense), 1.7.0 (aimFromView), 1.6.0 (manual returns and recall), 1.5.0 (mines), 1.4.0 (returning throws), 1.3.0 (per-shot behaviours), 1.2.0 (hooks). Requires physics.port 1 and game.engine 1.