Skip to content

simulatecraft.core.environment

simulatecraft.core.environment

Base Environment: subclass for any domain without touching the runner.

Snapshot

Bases: BaseModel

Domain-agnostic full-state snapshot served over REST / rendered by viewers.

Environment 

Environment()

Bases: ABC

Owns all mutable simulation state.

Contract
  • observe may return partial state (partial observability is supported).
  • step mutates state for one agent and returns a StepResult.
  • agent_ids must reflect dynamic membership (spawn/death/exit).
  • tick advances environment-owned state (weather, NPC timers, physics).
Source code in src/simulatecraft/core/environment.py 
32
33
34
def __init__(self) -> None:
    self._tick_count: int = 0
    self._registered: set[str] = set()

observe abstractmethod 

observe(agent_id: str) -> Observation | Awaitable[Observation]

Return the state visible to agent_id (may be partial).

Source code in src/simulatecraft/core/environment.py 
50
51
52
@abstractmethod
def observe(self, agent_id: str) -> Observation | Awaitable[Observation]:
    """Return the state visible to ``agent_id`` (may be partial)."""

step abstractmethod 

step(agent_id: str, action: Action) -> StepResult | Awaitable[StepResult]

Apply action for agent_id, mutating environment state.

Source code in src/simulatecraft/core/environment.py 
54
55
56
@abstractmethod
def step(self, agent_id: str, action: Action) -> StepResult | Awaitable[StepResult]:
    """Apply ``action`` for ``agent_id``, mutating environment state."""

tick 

tick() -> None | Awaitable[None]

Advance environment-owned dynamics once per simulation tick.

Source code in src/simulatecraft/core/environment.py 
58
59
60
61
def tick(self) -> None | Awaitable[None]:
    """Advance environment-owned dynamics once per simulation tick."""
    self._tick_count += 1
    return None

reset 

reset(seed: int | None = None) -> None

Reset to the initial episode state. Subclasses should override.

Source code in src/simulatecraft/core/environment.py 
63
64
65
def reset(self, seed: int | None = None) -> None:
    """Reset to the initial episode state. Subclasses should override."""
    self._tick_count = 0

snapshot 

snapshot() -> Snapshot

Full-state view for REST/viewers. Override to include world details.

Source code in src/simulatecraft/core/environment.py 
67
68
69
def snapshot(self) -> Snapshot:
    """Full-state view for REST/viewers. Override to include world details."""
    return Snapshot(tick=self._tick_count)