Deep GTA changes need more than a successful build. San Andreas Online combines executable guards, static checks, focused harnesses, matching client/server builds, and in-game passes so the documentation can state exactly what was exercised and what remains open.

Find Lua errors with DebugScript 4

Run debugscript 4 to open a full-screen Lua diagnostics view instead of reading mixed errors line by line in chat. It collects client and server messages in one place and shows what failed, which resource emitted it, whether it came from the client or server, and the source file and line when available.

Use the search box and the severity, side, or resource filters to isolate the problem. Repeated messages are grouped with a count, history can be frozen while you inspect it, and a capture can include the previous 30 seconds and continue for up to two minutes. Export the visible result as TXT for a quick report or JSON for tooling.

Press Ctrl+Shift+I or use devtools to toggle the view; Escape closes it. The original debugscript levels still work. The packaged frontend, store logic, and affected client/server projects were tested and built; a final post-build visual replay is not recorded as complete.

Develop a gamemode with an AI agent

The SA:O CLI for AI agents gives a coding agent the complete MTA + SA:O API, exact function contracts, project checks, generated context, and an optional path to verified in-game observations. Its dedicated guide covers setup and the full development loop.

Evidence levels

The wiki uses these terms deliberately:

Label	What it establishes
Implemented	The code path and registration exist in the documented revision.
Compiled	The affected project or producer/consumer set built successfully.
Statically checked	Parsers, formats, manifests, scripts, or resource files passed non-runtime validation.
Harness-tested	A focused automated or resource-level test exercised the named behavior.
In-game checked	The stated path was observed in a running client/server session. The scope must say single-client or multiplayer when that matters.
Experimental / unverified	The path exists, but the required runtime evidence is incomplete.

A lower level never implies a higher one. A build does not prove gameplay, and the existence of a test resource does not prove that every API in the same category was exercised by it.

How San Andreas Online is verified

The normal verification stack is:

1. patch guards confirm the exact supported GTA executable before native memory changes;
2. static checks cover formats, limits, ownership, cleanup, and failure paths;
3. affected client and server projects compile together when they share an ABI or protocol;
4. focused resources exercise one system at a time;
5. integrated resources combine systems under realistic lifecycle pressure;
6. in-game checks cover connection, restart, reconnection, stream cycles, cleanup, and ordinary San Andreas behavior after the feature is disabled.

The required depth depends on the change. Lua/resource-data work may need parsing and a resource restart but no C++ build. Native memory, serialization, protocol, or ABI changes need every affected producer and consumer plus an appropriate runtime pass.

Extended-world pipeline

utils/extended-world contains:

• deterministic Perry and imported-city resource generators;
• IMG packing and compact metadata generation;
• radar extraction and catalog generation;
• model-store and executable patch validators;
• native-world manifest and closed-payload parsing;
• format-3 multi-IMG packaging, aggregate no-mutation planning, selected-set envelopes, and registrar-generation checks;
• reviewed Bullworth, Vice City, Liberty City, and Carcer City radar-resource generation;
• immutable cache identity and publication tests;
• transport, startup authorization, and server-isolation policy tests.

Generated city game assets remain outside Git.

The native-world generator pins its RenderWare conversion step to Southland-FR/librw commit e91821e09ca9957e22c99ecf32438d8098c0ea75. That keeps regenerated payloads reproducible instead of silently following a moving converter branch.

Focused test resources

Representative resources include:

Area	Harnesses
World boundaries	extended-world-test, extended-water-test, pickup-position-test, seabed-boundary-test
Native pools	corona-limit-test, marker-limit-test, renderer-limit-test
Rendering	project2dfx-test, fog-distance-test, cull-zone-test, cull-mirror-floor-test, extended-radar-test, and generated native-world radar resources
Models and streaming	server-model-registry-test, city-residency-coordinator, native-simulation-lease-test, and generated city resources
Synchronized traffic	native-ped-traffic for civilian proposal, owner epochs, native Wander, avoidance, threat, damage response, moving-vehicle/airborne reactions, jump/climb handoff, cop locomotion and patrol, couple formation and presentation, observer presentation, and deterministic cleanup
Dynamic world objects	world-object-scripting-harness for proxy discovery, live transform tracking under player and vehicle pushes, damage/break feedback, matrix read/write, refused destroyElement, a push objective, and stream-out/stream-in element identity
Runtime collision	CRuntimeColModel_Tests unit tests for serialization, multi-mesh index offsetting, and rejection cases; runtime-collision-wall-demo for interactive wall/ramp drawing, live rebuilds while standing on the shape, a collision outline, and a vehicle impact test
Dynamic object physics	dynamic-object-physics-harness for gravity, collision rebound and settling, live linear and angular velocity, frozen state, stream-out and stream-in persistence, and a two-client syncer-change check
Managed ropes	rope-test for synchronized creation, every state getter and setter, holder and offset tracking, object and vehicle cargo, client-local ropes, server expiry, twelve logical ropes against eight native leases, the missing-holder crash regression, and coexistence with createSWATRope; rope-showcase for the cinematic
Custom foliage	foliage-test for the seven-function regression, runtime surface probing, density bounds, dimension and lifetime behavior, and a 64-slot cap test; foliage-draw-demo for interactive triangle drawing with live surface and density changes
Managed fire	fire-test for element creation, lifetime and remaining time, live strength, damage masks, source and target setters, client synchronization, server expiry, spread generations, more than 60 simultaneous fires and cancellable damage; fire-showcase for the cinematic
Scriptable birds	bird-test for creation and type identity, property round-trips, freeze behavior, invalid inputs, 128 simultaneous birds, and shot events with a cancel case; bird-showcase for the cinematic
Model 2DFX effects	2dfx-test for resource-stop cleanup, malformed-input rejection, custom add/get/set/reset, native effect editing and restore, and explicit global-restream stress up to 50 cycles; 2dfx-showcase for the cinematic
Object fracture	break-test for fracture creation from streamed geometry, element identity, fragment and triangle introspection, pause state, deterministic cache reuse, durability profiles, invalid arguments and simultaneous effects; break-showcase for the runway sequence and interactive playground; break-explosion-test for explosion-driven damage using real createExplosion calls, radial falloff, weak-rocket scaling and the zero-health transition
Story primitives	focused go-to, enter, exit, drive-wander, route, drive-by, mission-ped, gang-tag, camera, cutscene, braking, audio, and recording resources
Mission checkpoints	sweet-and-kendl, og-loc, tagging-up-turf, drive-thru, nines-and-aks, story-entry-exit-runtime, and story-entry-exit-test
Compatibility	fastweaponstrafe-toggle, world-sync-regression-test, packet capability tests, and mixed-recipient serialization cases
Native world	legacy transport/startup resources plus format-3 child-pack, selected-set, aggregate planner, cache, registrar, and generation-fence harnesses
Multi-client development	isolated -cl2 client state and the MTA Neon Duo launcher described in MULTI_CLIENT.md
Performance	entity-performance-test with repeatable model, collision, native-cost, and traversal profiles; fps-counter for a simple local /fps display

An API page labels an explicitly assigned resource as Test resource. When it only inherits a category-wide pointer, the page says Related category harness; that is discovery help, not a direct per-function validation claim.

Current verification matrix

System	Strongest evidence	Not yet proved
Extended coordinates and world RPCs	Boundary resources, mixed-recipient serialization tests, and in-game extended positions	Every upstream API at the full boundary and every third-party resource assumption
Radar, water, pickups, and seabed	Focused lifecycle resources and in-game extended-world checks	A complete world package with all optional GTA subsystems
Renderer and native pools	Focused stress resources exceeded historical ceilings; the 20,363-light startup catalogue and private 25,000-entry Project2DFX queue were checked in game	Every capacity under one production workload, broad distant-light performance, and the post-fix headlight/shader visual pass
SkyGFX	Affected projects built; selected color/radiosity and later YCbCr paths were checked in game	Full SkyGFX or PS2 parity, every weather/resolution/mod combination, and a broad performance matrix
San Andreas Online client and server browser	Startup, navigation, joining, localization, artwork, and cache paths received targeted implementation/runtime work	One exhaustive clean-install, DPI, aspect-ratio, offline, password, cache, and language matrix
SA:O account	Service tests and development OAuth/ticket/required-auth flows; two real server restarts verified automatic key creation and stable identity; neon-identity-connect-test checks the connection-event values, getter agreement, and pre-join cancellation	One checked-in MTA pass covering every getter and identity-aware ban path, key-rotation overlap, and a general owner portal
Custom vehicle audio	Client build plus manual AE86/Soundize-bank and BUST gameplay runs	A public reproducible config/bank resource and a focused automated or multiplayer playback matrix
Custom model registry	Server/client registry harnesses plus spawn, replacement, free, and parent-fallback runtime checks	Universal behavior for arbitrary resource combinations and legacy fallback expectations
Native world packs	Format-3 multi-IMG transport, exact selected-set audit, first admission in the same GTA process without a required restart, four-city generations 2–29, direct switching, bank reuse, reconnect, resource/server restart, non-contiguous selection, ten same-process server switches, a different four-pack to three-pack switch, and the forced restart fallback. The checked cache runs measured about 9 seconds in a fresh process and 1–4 seconds when reusing the same process.	Every possible custom pack or one-to-eight-pack combination, optional GTA subsystems, a true D3D device reset, and universal loading times across different hardware and packs
Synchronized NPCs and road traffic	Two-client runs covered pedestrian spawning and behavior, group/couple and owner handoffs, combat and cleanup; road-traffic passes covered atomic vehicle/occupant creation, DriveWander, passenger entry, owner changes, stuck recovery, destruction, and cleanup. The current production allocation is 16 vehicles per player area with a global cap of 160, and 12–20 pedestrians per populated area with a global cap of 240. Nearby players share population instead of multiplying the same crowd.	Boats, aircraft, trailers, parked-car generation, mission routes, emergency services, headless simulation, universal task snapshots, perfect collision-frame agreement, and sustained production performance at the configured population ceilings
Ambient cops	A two-client cop-locomotion oracle requiring three metres of native patrol, one owner at a time, an unchanged wanted level, no forbidden police task, one handoff epoch, and two cleanup ACKs	Rare path and RNG branches are recorded as evidence rather than required outcomes; there is deliberately no pursuit or arrest behavior to prove
Ambient couples	Atomic pair formation, leader selection from native walk speeds, and the separate observer presentation lease, with per-member reciprocity and role diagnostics	Long-run couple churn under heavy density and every native walk-side branch
Dynamic world objects	Client-only harness covering discovery, live transforms under player and vehicle pushes, damage and break events, matrix writes, destroy refusal, and preserved element identity across stream-out and stream-in	Server-side or synchronized behavior, object health and break-state properties, and behavior under arbitrary Lua-driven transform fighting
Runtime collision generation	Unit tests for mixed sphere/box/mesh serialization, multi-mesh index offsetting, and each rejection path; an interactive resource covering live rebuilds while a player stands on the shape, shape switching, and vehicle impact	Large mesh models at the documented ceilings, sustained per-frame regeneration cost, and every GTA surface material’s physical response
Dynamic object physics	A harness covering fall, rebound and settle, live velocities surviving object sync, and manual two-client syncer-change and stream-cycle checks	Sustained load with many physical objects at once, and behavior on models whose collision is unsuited to rigid-body simulation
Managed ropes	A two-sided pass/fail harness covering state round-trips, native activation and interpolation, cargo attachment, slot leasing beyond the native cap, and a dedicated regression for the holder-dereference crash	Long-run behavior with sustained lease churn, and every native rope type under multiplayer load
Custom foliage	A scripted regression over all seven functions, density bounds, degenerate-triangle and out-of-range rejection, dimension change and restore, OOP registration, and element-group teardown; plus create/destroy stress cycles	The rendered plant count, which GTA owns and Lua cannot read back; behavior under a natively saturated plant pool, where a sub-64 cap result is inconclusive rather than a failure
Managed fire	A pass/fail harness covering creation, lifetime and remaining time, live setters, damage masks, source and target, client synchronization, server expiry, one-generation spread, more than 60 simultaneous fires, and a cancelled damage event; plus a manual late-join check that a mid-burn joiner receives the reduced remaining lifetime	Long-run spread across many generations, damage balance against native fire, and sustained load well beyond the 68 fires the showcase places
Scriptable birds	A pass/fail harness covering creation, every property round-trip, freeze behavior, invalid input rejection, 128 simultaneous birds, and both the destroy and cancel paths of the shot event	Long-run flock performance, and how managed birds behave alongside a fully saturated native ambient bird population
Model 2DFX effects	A pass/fail harness covering cleanup across resource restarts, rejection of malformed properties and oversized names, custom and native effect editing, count semantics, and repeated global restreams	Every effect type under a production workload, and the streaming cost of large numbers of custom effects
Object fracture	A pass/fail harness covering fracture from live geometry, introspection, cache reuse, durability profiles including the zero-health transition, invalid arguments and multiple simultaneous effects	Fracture cost on high-triangle models, and how many simultaneous effects a production scene can sustain
Story primitives	Focused task, lease, camera, cutscene, audio, text, recording, gang-tag, and route checks; reusable two-client channels cover locomotion, ordered animation, fight/chat, weapon audiovisuals, and selected physical responses	General task completion events, arbitrary syncer reconstruction, universal task presentation, and frozen-owner heartbeat recovery
Mission checkpoints	Sweet & Kendl and OG Loc each completed two consecutive two-client headless passes; Tagging Up Turf has a complete two-client success path; Drive-Thru has two-client pursuit coverage plus a complete single-client return; Nines has partial runtime coverage	Complete natural visual/audio replay for the two newest missions, remaining branches, and the incomplete Drive-Thru and Nines multiplayer matrix; see Mission checkpoints
Compatibility and packaging	Capability-gated ordinary layouts, exact San Andreas Online native-world protocol rejection, installer/package checks, localhost connection, packaged Windows and Linux x64 server startup smoke tests, and Linux ARM64 package inspection	Linux ARM64 startup, runtime validation of fastweaponstrafe, and every experimental feature in the public package

This matrix is intentionally scoped. Exact timings, temporary ticket IDs, build-log excerpts, and one-off debugging observations belong in commits or test records rather than the evergreen guide.

Local asset previews

San Andreas Online includes developer-only drop workflows:

• one DFF and optional TXD can preview a replacement of the local player’s current base skin;
• one IFP loads an animation list; a single animation starts immediately, while several animations open searchable controls for looping, freeze-last-frame, root motion, speed, and blend.

Inputs are size-bounded and use existing validation and replacement paths, but there is no server authorization. These are local development tools, not secure multiplayer features.

Reading API provenance

Each SA:O API page keeps its implementation source and introducing or extending commit. Where known, it also links a direct test resource. These links provide traceability; they do not replace the evidence scope stated in the guide or matrix.

For playable story coverage, use Mission checkpoints. For native-world security, lifecycle, and current boundaries, use Native world packs.