Environment API
Bring your own agent.
Clone a world, plug in your agent and run it locally. JavaScript or Python. No API key or ML framework required.
1. Clone and run
Requires Node.js 22+. Python 3.10+ is optional. Run from the cloned repository; no package installation is needed for these examples.
git clone --branch browser-environment --single-branch https://github.com/Nova-Rift/survival-env.git
cd survival-env
node browser/run-agent.mjs --env island-v1 --agent ./examples/agents/random.mjs --seed 0The baseline prints a result for each episode. It uses random actions, not a trained model.
Social game
Private conversations, invitations, requests to join, voluntary participation, group exclusions and a mandatory vote. No survival mechanics. Read the social-v1 API or run the local simulator.
2. Choose a world
| Environment ID | What changes | Reward |
|---|---|---|
island-v1 | Food, storms, exposure and mandatory voting. | Winner +1; everyone else 0. |
survival-v2 | The original grid / mouse-meadow rules. | +1 per alive player, per movement turn. |
legacy-v1 | The original resource-depletion world. | +1 per alive player, per movement turn. |
3. Add your agent
Save this as my-agent.mjs. Each player gets its own instance and local observation. Replace the decisions with your model; async methods are supported.
export function createAgent({id, seed, observationShape}) {
return {
act({observation, reward, tick}) {
return 0; // Your model chooses: wait, north, east, south, west.
},
vote({candidates, councils}) {
return candidates[0]; // Choose another remaining player.
}
};
}node browser/run-agent.mjs --env island-v1 --agent ./my-agent.mjs --seed 0 --episodes 3Prefer Python?
The Python wrapper calls the same Node rules through a local subprocess. Use it from the source checkout.
from survival_env.api import Environment
with Environment("survival-v2", seed=0) as env:
state = env.reset()
while not state["done"]:
# Replace the wait actions with your agent's decisions.
state = env.step([0] * env.agent_count)For an island example including votes:
python -B -m examples.custom_agentThe small API
reset()- Start a fresh episode. Pass a seed to repeat a world.
step(actions)- Apply one movement action per player. 0 wait, 1 north, 2 east, 3 south, 4 west.
vote(targets)- At council, every remaining player chooses someone else. Use null / None for inactive slots.
frame()- Full-world data for a renderer or debugger; keep it out of local agent inputs.
Each transition returns observations, rewards, per-player termination/truncation flags, episode completion, the current phase and public council state. Agent IDs and vote targets are zero-based.
Observations, training and reproducibility
Observations are flattened channel-first local views: 8 × 5 × 5 by default; legacy uses 5 channels. They describe nearby food, self, nearby players, valid cells, own energy, active hazards, wear and health.
Movement pauses during council. Vote when phase === 'council'; reset after done. A living player at a time cutoff truncates; elimination and a last-player win terminate. The island has no survival-step reward.
The JavaScript runner supports an optional learn(transition) callback for movement and council decisions. Model loading, replay, optimizers and language providers are yours to choose.
Record the Git commit, environment ID, configuration and both environment and agent seeds. The Python wrapper runs the same JavaScript engine; the older native NumPy engine uses a different random generator.
Full shapes, semantics and examples ↗This is a local library API, not a hosted inference service or a Gymnasium/PettingZoo adapter. The separate Target Drift UI demo is outside this API.