Metadata-Version: 2.4
Name: evennia-archive
Version: 0.1.0
Summary: Archives Evennia accounts and characters into a separate database so you can rebuild your world without losing your players.
Author: Tim Baird
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/FullCircleMUD/evennia-archive
Project-URL: Repository, https://github.com/FullCircleMUD/evennia-archive
Project-URL: Issues, https://github.com/FullCircleMUD/evennia-archive/issues
Keywords: evennia,mud,backup,archive,restore
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: evennia
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# evennia-archive

Archives Evennia accounts and characters into a separate database so you can rebuild your world
without losing your players.

## Status

**Working, not yet used by a real game.** All four calls are built and tested —
objects and accounts can be archived, found, restored and deleted, with identity surviving and dbrefs
deliberately not. References between objects are dropped rather than rebuilt, and nothing has been
tested on PostgreSQL. See [docs/progress.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/docs/progress.md) for what exists and what proves it.

## The problem it solves

Evennia identity is the `ObjectDB` primary key. Rebuild your world and those keys are re-issued from
scratch, so a character's rows cannot simply be restored — the references inside them point at objects
that no longer exist, including references buried inside pickled attribute values.

That makes "rebuild the world from source" and "keep the players" hard to have at the same time.

## The approach

A second Evennia database, on the same schema, migrated alongside the game and **never run as a game**
— no rooms, no mobs, nothing instantiated. Account and character rows are copied into it as they
change. Because both ends share a schema, attribute values move as opaque bytes and are never parsed.

What replaces that work is reference translation: every stored reference is resolved to a stable
identifier on the way in, and back to whatever primary key the object receives on the way out.

## Is this for you?

Probably, if you rebuild your world from source — YAML, batch scripts, a world builder — and want
player characters to survive the rebuild.

Probably not, if you are looking for database backups. This is not `pg_dump`; it holds a live,
queryable record of accounts and characters, and it is not a substitute for backing up your database.

## Install

```
pip install evennia-archive
```

Editable install for development against a checkout:

```
git clone https://github.com/FullCircleMUD/evennia-archive.git
cd evennia-archive
python -m venv venv
# Activate the venv (platform-specific)
pip install evennia
pip install -e .
python runtests.py
```

Installing the package is not enough on its own — a consumer declares the app, a second database
alias and a router in their own settings. **See [docs/archive-settings.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/docs/archive-settings.md)
for what to add**, including the one entry that will silently break a game that already has database
routers.

## Learn more

- [docs/INDEX.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/docs/INDEX.md) — the design wiki
- [docs/design.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/docs/design.md) — the whole design, with a box above everything not yet settled
- [docs/archive-settings.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/docs/archive-settings.md) — what a consumer declares in their settings
- [docs/interoperability.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/docs/interoperability.md) — this library against its siblings
- [CLAUDE.md](https://github.com/FullCircleMUD/evennia-archive/blob/main/CLAUDE.md) — context for LLM agents working in this repo

## Licence

BSD 3-Clause. See [LICENSE](https://github.com/FullCircleMUD/evennia-archive/blob/main/LICENSE).
