gun that shoots bullets when the player clicks

Projectiles are a SCRIPT PATTERN. There is no ProjectileComponent or HitscanWeaponComponent. Bind a fire action, then either spawn a projectile prefab and launch it with a physics command, or resolve an instant hit with a physics shapecast. Damage lands via a trigger on the projectile or the shapecast result.

throw a grenade or fireball projectile

Projectiles are a SCRIPT PATTERN. There is no ProjectileComponent or HitscanWeaponComponent. Bind a fire action, then either spawn a projectile prefab and launch it with a physics command, or resolve an instant hit with a physics shapecast. Damage lands via a trigger on the projectile or the shapecast result.

hitscan raycast weapon that hits instantly

Projectiles are a SCRIPT PATTERN. There is no ProjectileComponent or HitscanWeaponComponent. Bind a fire action, then either spawn a projectile prefab and launch it with a physics command, or resolve an instant hit with a physics shapecast. Damage lands via a trigger on the projectile or the shapecast result.

spawn a bullet that damages enemies on impact

Projectiles are a SCRIPT PATTERN. There is no ProjectileComponent or HitscanWeaponComponent. Bind a fire action, then either spawn a projectile prefab and launch it with a physics command, or resolve an instant hit with a physics shapecast. Damage lands via a trigger on the projectile or the shapecast result.

Projectiles bullets and ranged weapons

The recipe

Author with project_apply_script_semantic_patch using the ai_safe op pack.

Bind the trigger: declare a fire action (see input-mapping-actions-bindings) and addActionHandler { "actionKey":"fire" }.
Spawned projectile (grenade, arrow, fireball): build a projectile prefab once with project_create_prefab carrying a RigidBodyComponent and a trigger ColliderComponent (collision:"trigger"). In the fire handler, spawnEntityFromTemplate { "prefabKey": <projectile>, "config": {...} } at the muzzle, then push it with ctx.physics.command using a launch body command (VelocityComponent's contract note: launch bodies via Physics.command { type: "launch" }; never patch VelocityComponent directly, it is engine-internal). Damage on contact via addTriggerHandler on the projectile that applies damage (see combat-damage-and-respawn) and despawnEntity the bullet.
Hitscan (instant hit): in the fire handler body (GessaScript via replaceScriptFromGessaScript), call ctx.physics.shapecast from the muzzle along the aim direction; if it returns a hit, apply damage to the hit entity and spawn an impact effect. No projectile entity is spawned.
Rate limit: guard the fire handler with a cooldown (a TimerComponent or a last-fired timestamp in state; see timers-countdowns-and-waves) so holding fire does not spawn one bullet per tick.
Muzzle flash and impact: pair with particles-and-visual-effects for the burst and a DecalComponent scorch at the hit point.

Pitfalls

Never write VelocityComponent to move a bullet; it is hidden from AI/SDK and runtime-owned. Launch through ctx.physics.command.
spawnEntityFromTemplate and ctx.world.spawn are authority-gated (spawn.bounds); spawn on the server, at a bounded position near the muzzle.
Bullets that never despawn accumulate and hit the collider budget (1000 per tick). Despawn on impact and add a lifetime timeout.
A projectile collider must be trigger, not solid, or it will be blocked by the target instead of passing through and reporting the hit.
Aim direction must come from the shooter's facing (camera or transform), resolved in the handler; there is no built-in "forward vector" field to read blindly.

Verify

simulation_run (qa.run.start) to prove a shot spawns and travels, a hit applies damage, and the projectile despawns on impact or timeout.
project_get_graph_snapshot to confirm the fire action handler and the projectile prefab exist.

The recipe

Pitfalls

Verify

On this page