Let scripts remove, restore and edit the map's own occluders

[Flashmyname]

Summary

The other half of #4079, on top of #5378. That one adds occluders, this one lets scripts remove, restore and edit the ones the map loads.

table engineGetOccluders ( [ bool interior = false ] )
bool  engineRestoreOccluder ( int id )
int   engineRemoveOccluders ( float x, float y, float z, float radius [, bool interior = false ] )
int   engineRestoreOccluders ( float x, float y, float z, float radius [, bool interior = false ] )

-- free the occlusion of the district you are replacing, then spend the slots on your own
local freed = engineRemoveOccluders(2400, 2400, 20, 300)
engineAddOccluder(2400, 2400, 20, 80, 2, 30)

-- or pull the police station's own occluder over the building you put in its place
local zones = engineGetOccluders()
engineSetOccluder(zones[1].id, 2400, 2400, 20, 60, 4, 40)
engineRestoreOccluder(zones[1].id)   -- back to what the map loaded

engineRemoveOccluder and engineSetOccluder take a map occluder id as well, and engineGetOccluderCapacity counts a removed one as free.

Neither a removal nor an edit touches the loaded entry, so a restore gives back the geometry the IPL loader wrote. Both end when the resource that asked for them stops.

Ids are per client and follow map load order, so read them from engineGetOccluders instead of hardcoding them.

Motivation

On a stock install the map already uses 995 of the 1000 exterior slots, so #5378 has five to work with. The ones in use still cull the buildings the map shipped with, even where those have been removed.

Test plan

Test resource: occedit.zip

53 checks run on join and print to the server log. The commands cover the whole API:

/occfind [radius] [interior]                      list what is near you, nearest first
/occdel  id                                       engineRemoveOccluder
/occback id                                       engineRestoreOccluder
/occwipe [radius] [interior]                      engineRemoveOccluders
/occundo [radius] [interior]                      engineRestoreOccluders
/occmod  id x y z [sx] [sy] [sz] [rx] [ry] [rz]   engineSetOccluder on a map occluder
/occpull id                                       drag one to where you stand
/occdraw [radius]                                 outlines, green still in, red held out
/occcap  [interior]                               engineGetOccluderCapacity

Checklist

• Your code should follow the coding guidelines.
• Smaller pull requests are easier to review. If your pull request is beefy, your pull request should be reviewable commit-by-commit.

[Flashmyname]

Updated along with #5378. engineSetOccluder now takes a map occluder id as well, so the map's own occlusion can be moved rather than only removed:

local zones = engineGetOccluders()
engineSetOccluder(zones[1].id, 2400, 2400, 20, 60, 4, 40)
engineRestoreOccluder(zones[1].id)   -- back to what the map loaded

The original entry stays as the IPL loader wrote it, so that is what a restore gives back. Only one resource can hold an edit, and when it stops the occluder goes back to normal.

The test resource covers the whole API from commands now, listed in the description.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Fixed-address native memory manipulation and occluder-list rebuilding require final human review and runtime validation.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify UndoOccluderChanges restores all owned occluder changes · New

What changed in this PR

Adds Lua APIs for querying, editing, removing, and restoring GTA map occluders with resource-scoped cleanup.

Changes:

• Exposes occluder management APIs to Lua.
• Snapshots and safely rebuilds native occluder pools.
• Restores resource-owned changes during cleanup.

Commit messages should retain the motivation, implementation reasoning, and testing details.

File	Description
Client/​sdk/​game/​CWorld.h	Defines occluder data and world APIs.
Client/​mods/​deathmatch/​logic/​luadefs/​CLuaEngineDefs.h	Declares Lua-facing functions.
Client/​mods/​deathmatch/​logic/​luadefs/​CLuaEngineDefs.cpp	Implements validation and Lua bindings.
Client/​mods/​deathmatch/​logic/​CResource.cpp	Cleans up resource-owned changes.
Client/​mods/​deathmatch/​logic/​CClientGame.cpp	Resets occluders on game initialization.
Client/​game_sa/​CWorldSA.h	Defines native pool structures and state.
Client/​game_sa/​CWorldSA.cpp	Implements capture, rebuild, editing, and restoration.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.