VIRUXE/scavengesurvive-mta

Scavenge & Survive for MTA:SA

PvP survival on a decayed San Andreas. Scavenge & Survive, the SA-MP gamemode by Southclaws, rebuilt for MTA:SA 1.6 in Lua on MariaDB: one alive character, everything is a physical item on the ground, wounds bleed, and death drops it all.

What works today

Progress is tracked in the issues and the project board; each milestone is an epic there.

Apparel is checked in the green-screen studio (docs/dev-studio.md): one ped, a fixed camera, every skin in a row.

How it is built

• One MTA resource per domain, no prefix: lib, data, models, maps, ui, auth, character, items, loot, vehicles, crafting, building, world, weapons, chat, hud, staff, dev, attachedit. They share state only through MariaDB, so any resource can restart alone and rebuild from the database.
• MariaDB does the heavy lifting. Every item-graph move (pickup, drop, container put/take, death drop) is a stored procedure that returns ok, code, payload; positions are POINT columns with spatial indexes. The schema is one sql/schema.sql dumped from the database; there are no migration files.
• Scarcity is a budget, not a timer. Loot and vehicles have a carrying capacity (per zone for loot) that refills in proportion to what is missing, with per-point cooldowns and nothing respawning within 150 m of a player. What players carry still counts, so hoarding slows the whole server down (ADR 0001).
• The dev server is driven from the shell. rcon.ps1 runs commands and key presses as any player, Lua, screenshots and the chat lines a client received (screenshots omit the chat box) over the dev resource's HTTP export; /studio puts a ped alone on a chroma-green set and attachedit tunes attachment offsets in game.
• Static world on the client. The 221 upstream map files become createBuilding calls spread over frames (about 1.3 s on join), with the 209 SA-MP-only object models shipped in the models resource.
• Damage is server-authoritative. The victim's client reports a hit; the server checks the shooter's held weapon, range and rate, computes the wound and applies it.
• Pure logic is testable. Formulas live in shared/logic/*.lua with no MTA calls, so busted runs them on plain Lua 5.1; converters and SQL procedures have pytest coverage, the SQL tests against a live MariaDB.

Design: docs/superpowers/specs/ (Appendix A is upstream behaviour, Appendix B the verified MTA facts). Decisions: docs/adr/. Conventions every contributor and agent follows: CLAUDE.md.

Quick start (Windows)

1. pwsh tools/setup-dev.ps1 — Lua 5.1 toolchain, stylua, Python deps.
2. MariaDB 13.0 as a local service (root, no password) and MTA:SA 1.6 client + server installed.
3. pwsh server-config/run-local.ps1 — creates the database, applies sql/schema.sql, procedures, triggers, events and seeds, links the resources into the server and starts it. Connect to 127.0.0.1:22003.
4. Give yourself staff rights: mariadb -u root scavengesurvive -e "UPDATE accounts SET admin_level = 5 WHERE name = 'You'", relog, /acmds (docs/staff-commands.md).
5. Drive the running server without touching the console: pwsh server-config/rcon.ps1 help (players, resource restarts, chat commands and bound keys as any player, Lua, screenshots, chat <player> to read a client's replies). Details in server-config/README.md.

Before committing, the four local checks must pass (there is no CI; commits land on main):

.lua\bin\busted.bat tests/lua
.lua\bin\luacheck.bat resources
stylua --check resources
pytest -q

Documentation map

Toolchain notes

setup-dev.ps1 builds Lua 5.1.5 with hererocks' default target, which picks MSVC (--target vs) when Visual Studio C++ Build Tools are installed (verified with Visual Studio Community 2026). Without MSVC, install a MinGW toolchain (winget install -e --id BrechtSanders.WinLibs.POSIX.UCRT), put its mingw64\bin on PATH, and run python -m hererocks .lua -l 5.1.5 -r latest --target mingw before setup-dev.ps1 (the script then switches LuaRocks from hererocks' MSVCR80 link default to ucrt; a native rock that still imports MSVCR80.dll fails to load with "The specified module could not be found" — rebuild it with .lua/bin/luarocks.bat build <rock> --force). MariaDB installs as a Windows service from winget: winget install -e --id MariaDB.Server --override "/qn SERVICENAME=MariaDB ADDLOCAL=ALL PORT=3306" (root with no password, which is the project default). The MSI does not add its bin to PATH; add it, since run-local.ps1 and the smoke checklist call mariadb by name.

Credits and licences

Scavenge & Survive is Copyright (C) Barnaby "Southclaws" Keene and the community that built its maps from 2008 to 2017. New code here is released under the Unlicense; converted upstream data stays MPL-2.0 and the map placements CC BY-SA 4.0; the SA-MP object models belong to the SA-MP team. See THIRD_PARTY_NOTICES.md.