Skip to main content

Project 02: Ped spawner

In Project 01, you altered a global environment setting. In Project 02, you create your very first physical living entity inside Los Santos. Your goal is to build a robust keyboard spawner: stream an actor model into memory, place the pedestrian directly ahead of the player using spatial vector math, guard strictly against double spawning, and guarantee that the entity is deleted cleanly both on demand and when reloading the script.

The mission​

Build a resilient pedestrian spawner satisfying five essential requirements:

  1. Stream a specific NPC character model asynchronously into memory with timeout safety.
  2. Calculate a 3D position 2 meters directly ahead of the player using vector arithmetic.
  3. Spawn the pedestrian facing the player's direction when pressing NumPad 1.
  4. Guard strictly against duplicate spawns: refuse creation and notify the player if an entity is already active.
  5. Delete the entity immediately when pressing NumPad 0, and guarantee zero entity leakage when reloading.

Specifications, constraints​

  • Memory hygiene: Always release the model handle with MarkAsNoLongerNeeded() inside a finally block so streaming assets do not leak in RAM.
  • Single active entity: Track the pedestrian using a private field _spawned and verify both _spawned != null and _spawned.Exists() before any action.
  • Spatial vector math: Compute world spawn coordinates using player.Position + player.ForwardVector * 2f.
  • Zero entity leakage: Implement clean teardown in OnAborted so reloading the script never leaves ghost NPCs behind in the world.

Implementation steps​

  1. Track entity state: Define a private field private Ped _spawned; in your script class.
  2. Wire lifecycle events: In the constructor, register event handlers for KeyDown and Aborted.
  3. Guard against duplicates: At the start of your spawn routine, check if _spawned is non-null and currently exists. If so, post a ticker notification and return early.
  4. Stream the asset model: Instantiate a Model with PedHash.Trevor and call model.Request(2000). If the request times out or the asset is invalid, release the model and exit.
  5. Calculate offset and instantiate: In a try-finally block, obtain Game.Player.Character, calculate the position 2 meters ahead using player.ForwardVector, and call World.CreatePed.
  6. Release the model: In the finally block, call model.MarkAsNoLongerNeeded().
  7. Implement deletion: Build a helper method that checks if _spawned exists, calls _spawned.Delete(), and sets _spawned = null.
  8. Wire controls and teardown: Bind Keys.NumPad1 to spawn, Keys.NumPad0 to delete, and call your deletion helper in OnAborted.

APIs, tools to explore​

  • GTA.Model: Wrapper representing a game model asset in the game's CD image archives.
  • Model.Request(int timeout): Asynchronously streams model geometry, textures, and skeletons into RAM.
  • Model.MarkAsNoLongerNeeded(): Marks the asset as disposable so the engine can free memory when needed.
  • GTA.World.CreatePed(Model model, Vector3 position, float heading): Spawns a physical pedestrian into the game world.
  • Ped.ForwardVector: A normalized unit vector pointing directly forward along the entity's current orientation.
  • Entity.Exists(): Validates that an entity's native handle is currently valid, allocated, and present in the world.
  • Entity.Delete(): Removes the entity from the physical world and deallocates its native resources immediately.

Validation checklist​

Your mod is validated when:

  • Pressing NumPad 1: Trevor appears exactly 2 meters in front of the player, facing the same direction.
  • Pressing NumPad 1 a second time: A notification announces that a ped is already active, and no duplicate ped spawns.
  • Pressing NumPad 0: Trevor vanishes instantly, and the reference is cleared.
  • Spawning Trevor and pressing Insert to reload: Trevor disappears cleanly without leaving an orphan NPC in Los Santos.

Solution, explanations​

Partner
Verified solution and code explanations

The mission, specifications, and guided steps remain 100% free and open for everyone. The complete verified reference code and production explanations are reserved for Partner members.

Connect with PatreonBecome a Partner