AzerothAI/docs/hardcore-replacement.md

Hardcore population replacement

The game-side ALE lifecycle guard closes an identity permanently after death. It preserves character data and the AzerothAI memorial, removes the character from the random-bot manager, and refreshes a persistent login veto. Zaku and protected identities are excluded. GUID, account and name must all match the installation registry; human accounts are never included.

The installer promotes unused manual-summoning reserve accounts into the native autonomous pool. The native random-bot manager maintains its configured population target using unused factory-created characters. Replacements start at level 1, with their own names and AzerothAI recipes/memories assigned when observed. This does not reset or resurrect a dead character. Duplicate death events are harmless.

The reserve is finite: this deployment began with 450 unused level-1 characters. This release does not create additional accounts or extend the factory reserve when it is exhausted. The population will fall below target if no eligible characters remain. Check azerothai_lifecycle state counts before extending it. Death Knights are excluded from new random logins because they do not start at level 1. Normal gameplay can still level a replacement after its initial entry.

The guard allocates new arrivals against actual living faction counts, targeting 25 Alliance and 25 Horde, including protected residents. It holds excess-faction reserves and excess returning residents offline without retiring them. Returning residents retain their progress and get priority over unused reserves. New activations record entry_level=1; subsequent leveling is allowed. Native factory-created newcomers are enrolled only from verified RNDBOT accounts and only when fresh and level 1.

Installation

1. Build the updated AzerothAI application and start its runtime.
2. Run python3 deploy/playable/install-lifecycle.py --lab /path/to/lab to review.
3. Stop ac-worldserver.
4. Repeat the command with --apply. It backs up auth, character and playerbot databases, current Lua scripts, compose overrides and the dashboard state.
5. Recreate only the world container with docker compose up -d --no-deps ac-worldserver.
6. Restart the ALE relay to load priority delivery for permanent-death events.

The guard is enabled by installing its Lua file, independently of the dashboard hardcore toggle. Remove the guard and recreate the world before intentionally switching back to non-hardcore play. Do not erase the registry to recycle deaths.

Verification and recovery

Verify the lifecycle startup line, absence of lifecycle errors, zero retired GUIDs online, new reserve activations at level 1, and the native target count. The dashboard active count excludes unmanaged prototype entries in live mode.

For rollback, stop the world and restore its prior Lua directory and compose override from the printed backup directory, then recreate the world container. The previous characters were never deleted. Database restoration is a separate operator action: it also rolls back gameplay since the backup timestamp.

Run python3 tests/lifecycle-lua.test.py with lupa installed for isolated retirement, replay, protection and replacement-entry checks. Run node scripts/test-core.mjs for application tests.