OpenZT2 Reimplementation Plan

ORIGINAL-GAME-FUNCTIONAL-SPECIFICATION.md describes the original game domain: the source-owned files, native managers, object types, message contracts, state transitions, and behaviours the reconstruction must preserve. This document describes the engineering shape of the Rust runtime: how those contracts should be stored, loaded, indexed, simulated, and presented efficiently in a modern Bevy engine.

The specification answers "what did Zoo Tycoon 2 mean and require?" This file answers "how do we execute those same meanings without building a slow facade over a 2008 single-threaded C++ heap model?"

The reconstruction must remain backwards-compatible with the original source formats: Z2F archives, XML/MAXML/BFXML documents, localization files, materials, models, textures, audio, saves, and packages. It does not need to preserve the original C++ memory layout, allocator behaviour, STL container choices, pointer graph, vtable mechanics, or duplicate transient trees unless one of those mechanics is part of an observable or persisted contract.

Implementation Completion Tracker

This tracker is a work board for the Rust overhaul, with status assigned from the accepted functional specification, live Rust modules/loaders/systems, and the classified binary perimeter. It tracks current evidence state rather than percentage complete. A recorded row means Rust has records for a source/domain surface; source hydration and runtime execution are stated only when the capability cell names them. A row is ready for assignment when its Unlock cell names the first concrete source file family, handler group, binary contract, or runtime path to inspect or implement.

Badge meanings:

Source And Evidence

App, UI, Menus, And Modes

Entity, Animal, Guest, And World Systems

AI, Staff, Shows, And Behavior

Economy, Progression, Status, And Catalog UI

Scenario, Scripts, Save, And Photos

Renderer, Audio, Camera, And Host Adapters

Unknown Extent And Expansion Rule

Workspace Crate Boundaries

content owns source-file boundaries: shipped Z2F archive addressing, asset paths, XML/MAXML-like data documents, localization documents, parser support, and source references needed to recover where a value came from. Content code can parse, decode, normalize, and validate source documents; it does not own live game state or host projection state.

domain owns host-independent source-derived game concepts and original contracts: UI/document semantics, manager configuration, entity definitions, catalog values, rules, state transitions, command/event meaning, and invariants. Domain code receives loaded source documents and original-game messages, then returns values/results or mutates original-game state. It does not own Bevy resources, ECS entities, renderer buffers, mounted archives, asset caches, task pools, audio playback, or generic host registries.

Domain may define original-game semantic asset value types, tokens, validation rules, and pure transforms over loaded source data. It must not own the live loaded asset set: generic loaded-document collections, mounted archive mirrors, asset path indexes, Bevy handles, loader queues, or duplicate caches of Bevy asset values belong outside domain. Preserving an original ZT*, BF*, or BFG* symbol means naming the source/domain value type and its semantics. Runtime storage ownership still belongs at the boundary defined for that value.

bevy owns the executable runtime adapter: windowing, app lifecycle, task pools, mounted archive state, Bevy asset sources, asset extraction, resources, ECS entities/components, Bevy messages, input, rendering, audio playback, and projection of source/domain values into the live Bevy world.

Runtime Shape

The running game should use Bevy as the runtime world, scheduler, asset system, and presentation store. domain defines original semantic types, invariants, source-derived values, and mutation rules; bevy stores live state as Bevy resources/components and connects them to input, rendering, audio, assets, and schedules.

content
  Z2F/archive/path lookup
  source bytes
  BFXML/XML/MAXML parsed document assets

domain
  original semantic types and mutation rules:
    UI nodes/widgets/messages
    app lifecycle states
    managers
    modes
    entity/type records
    AI tasks
    terrain/world/camera concepts

bevy
  Bevy plugins, schedules, systems
  Bevy Assets for decoded source artifacts
  Resources/components containing domain types
  render/UI/audio/input adapters

StartupDomainResources publishes source-derived values during Bevy-adapter boot. Startup code may assemble values there, then immediately publish the result into Bevy resources/components without a second transfer bucket. The player-facing runtime should operate on the published resources directly.

Original singleton-like managers and runtime domains should live in coherent Bevy resources that match real runtime boundaries. Use one Bevy resource per old singleton only when that singleton is itself the recovered boundary:

ZTAppRuntime
ZTModeMgr
UiRuntimeContext
UiLayoutRegistry
BFGWorldRuntime
EconomyRuntime
BFLocaleMgr
EntityTypeRegistry
RendererRuntime
RuntimeSupport

Many-instance runtime objects should become Bevy entities/components carrying domain-defined state:

World entity:
  ZTEntityInstance
  EntityTypeRef
  BFPhysObj-derived transform/state
  AI runtime state
  mutable needs/disease/staff/etc. components as recovered
  render/audio/UI marker components where needed

The domain model remains intelligible outside Bevy because the types and handlers live in domain. The running storage is Bevy because Bevy is the engine's ECS, scheduler, change tracker, and asset-handle store.

Bevy Runtime Primitives

In the running executable, Bevy should provide the primary runtime substrate: storage, scheduling, change detection, asset handles, presentation, and host I/O. Original game contracts still live in domain types and handlers. Those types should be stored and executed through Bevy primitives where that improves locality, parallelism, and incremental updates.

App, Plugins, And World

App is the boot container. It wires plugins, resources, schedules, assets, states, diagnostics, windows, and render pipelines. OpenZT2 should use plugins as real subsystem boundaries:

SourceArchivePlugin
BfxmlPlugin
LocalizationPlugin
UiRuntimePlugin
ShellModePlugin
WorldRuntimePlugin
TerrainPlugin
RendererBridgePlugin
AudioPlugin
DiagnosticsPlugin

Each plugin should install the resources, components, systems, asset loaders, events/messages, and schedules for one original responsibility. Plugins register recovered domain meaning into the runtime.

World is Bevy's entity/resource storage. In the game executable, the Bevy world should hold the live runtime state directly. A separate domain graph that is copied into the world every frame is a performance smell. Headless tests may still create domain structures without Bevy. The player-facing runtime should treat World as the canonical mutable store for resources/components.

Entities, Components, Resources, And Bundles

Entities are ids for runtime instances. Animals, guests, staff, vehicles, placed objects, UI widgets, cameras, terrain chunks, effect emitters, and audio emitters can all be entities when they have independent lifetime or per-instance state.

Components are the runtime fields attached to those ids. Original concepts such as entity type references, component properties, AI task state, disease state, physics/object state, selection state, renderable model refs, and UI widget runtime state should be normal Bevy components when they are per-instance.

Resources are singleton or registry state. Original managers and global tables map naturally to resources: mode manager, world manager, status/economy manager, locale manager, archive repository, document store, UI layout registry, material registry, input focus state, and render configuration.

Use bundles as spawn/update ergonomics for coherent Bevy entities:

UiWidgetBundle
WorldEntityBundle
TerrainChunkBundle
CameraRigBundle
AudioEmitterBundle

The bundle should contain domain components and Bevy presentation components; it should not hide a second copy of the source record.

Systems, Queries, Commands, And Params

Systems are the runtime functions. Domain handlers should be called from systems that gather input from Bevy resources/components and write results back into Bevy storage.

Queries are how systems access entity sets. They are the right way to avoid linear scans of a giant session object:

Query<(&EntityTypeRef, &mut AiRuntimeState, &Transform), With<Animal>>
Query<(&UiSourceNode, &mut Visibility), Changed<UiWidgetRuntimeState>>
Query<(&TerrainChunkId, &mut MeshHandle), With<DirtyTerrainChunk>>

Commands are deferred structural mutations: spawning/despawning entities, adding/removing components, and inserting/removing resources. Use them for lifetime changes. Ordinary field updates should go through mutable queries/resources.

System params, including Res, ResMut, Query, EventReader, EventWriter, MessageReader, MessageWriter, Local, Commands, and ParamSet, are the way to make dependencies explicit. ParamSet is useful where an original handler needs mutually exclusive query shapes that Rust's borrow checker cannot otherwise express in one system.

Schedules, System Sets, Run Conditions, And States

Schedules should model execution phases. Product meaning belongs in domain state. Useful schedules/sets are:

StartupSourceMount
StartupDocumentHydration
InputCollection
DomainMessageDispatch
Simulation
PresentationSync
RenderPreparation
Diagnostics

System sets give stable ordering and parallelism boundaries inside those phases. Use them to separate source loading, message dispatch, simulation mutation, dirty projection, and diagnostics. Systems within a set should run in parallel when their data access permits it.

Run conditions are cheap gates. They should prevent inactive systems from touching irrelevant data:

run_if(in_shell_ui)
run_if(in_loaded_world)
run_if(resource_changed::<UiRuntimeContext>)
run_if(any_dirty_terrain_chunks)

Bevy states can control schedule activation such as Loading, ShellUi, and InGame3d. They must remain host scheduling state. Original app/mode state should remain explicit domain resources such as ZTAppRuntime, ZTModeMgr, or the recovered manager type.

Events, Messages, Observers, And Change Detection

Use Bevy events/messages for short-lived runtime facts:

OriginalUiProjectionCommandQueued
OriginalUiMessageQueued
TerrainRegionEdited
BFAudioCommandQueued

Original UI commands and game messages should be represented in domain terms, then transported through Bevy messages/events when the runtime needs decoupled delivery. Do not convert an original domain message into a Bevy-only callback that loses the original sender, target, payload, or ordering.

Observers are appropriate for local reactions to component or entity changes when they express host mechanics: attach a render child when a renderable component appears, start an animation when a UI visual state changes, or emit a diagnostic marker when a terrain chunk becomes dirty. They should not replace the original native message handlers.

Bevy change detection is central to performance. UI, terrain, world entities, materials, animation, audio, and cameras should update presentation only from Changed<T>, dirty sets, generation counters, or explicit messages. Avoid full-tree and full-world rebuilds.

Assets, Handles, Reflection, Scenes, And Serialization

Bevy assets should store decoded immutable artifacts: parsed BFXML documents, textures, sounds, models, materials, shader modules, scene fragments, and possibly compiled UI templates. Domain/runtime records should store ids or handles instead of copied payloads.

Handles are cheap references. They are the right representation for repeated texture/model/sound/material references across UI, entities, terrain, and effects.

Reflection and world serialization are developer/runtime tools. Use reflection for inspectors, diagnostics, and save/debug tooling where it helps. Keep the original source formats and type registries authoritative.

Scenes are useful for Bevy-native debug/test fixtures and imported GLTF content. Original Zoo Tycoon 2 layouts, entities, maps, and assets should still hydrate from their recovered source formats rather than being converted into Bevy scenes as the source of truth.

Tasks And Parallelism

The multi_threaded, async_executor, async-io, and task-pool surfaces are how expensive loading and hydration work should stop blocking the frame. Archive mounting, document parse, model/material decode, terrain chunk mesh generation, and thumbnail/icon preparation can run off the main thread, then report compact results back through messages or asset handles.

Parallel ECS systems should own normal frame work: AI ticks, animation state, dirty UI updates, terrain projection, audio command preparation, and visibility or culling data. The target is result compatibility with the original update loop, using Bevy's dependency graph to run independent work concurrently.

Bevy 0.19 Capability Map

This section treats the full Bevy 0.19 feature surface as the planning map, not just the subset currently enabled in bevy. Each feature family below should be considered when it improves either performance or fidelity to the original game. Feature flags are named explicitly so no major Bevy surface is lost in a vague "renderer" bucket.

Core Runtime And Platform

Relevant features:

default
default_app
std
default_no_std
default_platform
common_api
critical-section
libm
ff
multi_threaded
async_executor
async-io
bevy_app
bevy_ecs
bevy_tasks
bevy_time
bevy_state
bevy_transform
bevy_window
bevy_winit
wayland
x11
web
webgl2
webgpu
android-game-activity
android-native-activity
bevy_android
raw_vulkan_init
dynamic_linking
hotpatching

Use this surface for the engine frame loop, window/backend integration, task pools, app/schedule registration, time, transform propagation, and platform ports. Desktop OpenZT2 should prefer native Wayland/X11/wgpu paths. Web and Android remain portability targets for later work after the first faithful desktop reconstruction.

ECS, Scheduling, Reflection, Debug Storage

Relevant features:

bevy_ecs
bevy_ecs_macros
bevy_state
bevy_state_macros
schedule_data
bevy_reflect
bevy_reflect_derive
reflect_auto_register
reflect_auto_register_static
reflect_documentation
reflect_functions
bevy_world_serialization
serialize
track_location
type_label_buffers
debug
debug_glam_assert
glam_assert
detailed_trace
trace
trace_chrome
trace_tracy
trace_tracy_memory
bevy_debug_stepping

Use ECS/scheduling features for the canonical runtime layout. Use reflection and serialization for debugging, inspectors, automated validation, and save-tool helpers. Use tracing/debug stepping when investigating frame stalls, bad ordering, or runaway systems. Do not use reflection or serialized worlds as a replacement for original source formats.

Assets, File Watching, And External Formats

Relevant features:

bevy_asset
bevy_asset_macros
asset_processor
embedded_watcher
file_watcher
bevy_asset_loader
standard_dynamic_assets
progress_tracking
web_asset_cache
http
https
compressed_image_saver
zlib
zstd_c
zstd_rust

The target is a Z2F-backed asset path: mounted archives feed Bevy asset readers and loaders lazily. File watchers and the asset processor are useful for development rebuilds and generated/debug assets. Web cache and HTTP(S) are secondary surfaces. Compression features matter for archived payloads and future save/package handling.

Images And Texture Containers

Relevant features:

bevy_image
png
jpeg
tga
dds
ktx2
basis-universal
bmp
gif
hdr
exr
ico
pnm
qoi
tiff
webp
zlib
zstd_c
zstd_rust

Use Bevy image assets and GPU texture upload for UI skins, icons, terrain textures, decals, sky/lighting resources, particles, and model materials. Original texture references should hydrate to asset ids/handles; image bytes should not be copied into domain records. DDS/KTX2/Basis are important for GPU friendly compressed paths if original or converted assets justify them.

Audio

Relevant features:

audio
audio-all-formats
bevy_audio
wav
vorbis
flac
mp3
mp4
aac
symphonia-wav
symphonia-vorbis
symphonia-flac

Use Bevy audio for playback, handles, sinks, volume, looping, and eventually spatial attachment to world entities. Domain managers should produce original audio commands; Bevy owns the concrete sink/player state. WAV is currently closest to the shipped audio path, while broader formats remain available for tooling or later asset compatibility.

Input, Focus, Picking, And Interaction

Relevant features:

bevy_input
keyboard
mouse
touch
gestures
gamepad
bevy_gilrs
bevy_input_focus
bevy_picking
picking
mesh_picking
sprite_picking
ui_picking
bevy_clipboard
system_clipboard
clipboard_image
custom_cursor

Input systems should translate host events into original UI/game commands. Picking should replace ad hoc screen-coordinate scans for UI and world selection while preserving the original target/message semantics. Mesh picking is central for terrain/object placement, entity selection, and camera/world queries. Input focus is important for UI modal behaviour. Clipboard/gamepad are optional surfaces until an original behaviour requires them or they improve debug tooling.

UI, Text, Fonts, And Accessibility

Relevant features:

ui
ui_api
ui_bevy_render
bevy_ui
bevy_ui_render
bevy_ui_widgets
bevy_ui_debug
bevy_feathers
ghost_nodes
bevy_text
default_font
system_font_discovery
bevy_a11y
accesskit_unix

Use Bevy UI as the presentation and interaction backend for original UI documents. The authored UI layout remains the source contract. Bevy entities carry source node ids, visual state, text/image handles, layout components, focus/picking components, and dirty markers. Text/font handling must preserve the original font selection, localization, sizing, alignment, and color semantics. Default/system fonts only cover fallback and development use while original fonts are available.

2D Sprites, Atlases, Tiles, And UI Imagery

Relevant features:

2d
2d_api
2d_bevy_render
bevy_sprite
bevy_sprite_render
sprite_picking
bevy_color

Use 2D rendering for UI art, cursors, overlays, icons, previews, debug maps, and possibly tile-like minimap or editor layers. Sprite picking helps pointer dispatch. Atlas-style batching should be considered for UI skins and icon sets so the menu/frontend does not become thousands of independent texture binds.

3D Rendering, Meshes, Materials, And Models

Relevant features:

3d
3d_api
3d_bevy_render
bevy_render
bevy_core_pipeline
bevy_mesh
bevy_material
bevy_material_macros
bevy_shader
bevy_pbr
bevy_mikktspace
bevy_gltf
gltf_animation
scene
bevy_scene
bevy_scene_macros
bevy_world_serialization

Use Bevy mesh/material/render assets for terrain, water, paths, fences, animals, guests, buildings, vegetation, particles, and placement previews. Original BFB, NIF, BFMat, texture, and animation formats should hydrate through source/domain loaders into Bevy mesh/material/animation assets. GLTF scenes are useful for developer fixtures or converted inspection assets. Original files remain the canonical source.

Terrain Editing And Mesh Mutation

Relevant features:

bevy_mesh
bevy_render
bevy_pbr
mesh_picking
bevy_gizmos
bevy_gizmos_render

Terrain raise/lower/paint/flatten/path/fence placement should operate on domain terrain chunks and dirty regions, then update Bevy mesh assets for only the affected chunks. Mesh picking supplies brush hits and placement queries. Gizmos should visualize brush radius, selected cells, path/fence segments, surface normals, and dirty chunk boundaries during development.

Lighting, Shadows, Fog, Sky, And PBR

Relevant features:

bevy_light
bevy_pbr
area_light_luts
dfg_lut
bluenoise_texture
tonemapping_luts
pbr_anisotropy_texture
pbr_clustered_decals
pbr_light_textures
pbr_multi_layer_material_textures
pbr_specular_textures
pbr_transmission_textures
experimental_pbr_pcss
bevy_solari

Use these surfaces to approximate or surpass the original renderer while preserving visual intent: sun/ambient setup, time-of-day colour, shadows, terrain/object materials, decals, water/material effects, skybox/atmosphere presentation, and fog. The original renderer's material and lighting contracts must drive the inputs; Bevy can supply a modern implementation.

Post-Processing, Anti-Alias, Tone Mapping, Bloom, Blur, Color

Relevant features:

bevy_post_process
bevy_anti_alias
smaa_luts
tonemapping_luts
dlss
force_disable_dlss
hdr
bevy_color

Use post-processing to match the original game's visible output: gamma/color space, bloom-like effects, fog/color grading, anti-aliasing, and any screen effects recovered from renderer contracts. DLSS/HDR are optional modern capabilities; they must not change the default fidelity target unless exposed as explicit graphics options.

Shaders And GPU Pipeline Control

Relevant features:

bevy_shader
shader_format_glsl
shader_format_spirv
shader_format_wesl
spirv_shader_passthrough
statically-linked-dxc
raw_vulkan_init
meshlet
meshlet_processor

Use custom shaders for original-specific terrain blending, water, decals, foliage, UI effects, particle effects, and material features that standard PBR cannot represent. Meshlet features are a future optimization path for dense world geometry if profiling shows classic chunked meshes are insufficient.

Animation, Easing, Morphs, Timelines, And Effects

Relevant features:

bevy_animation
bevy_animation_macros
morph
morph_animation
gltf_animation
bevy_time

Use Bevy animation assets/systems for skeletal/model animation once original animation formats are mapped. Morph support is relevant for facial/body morphs or converted model data if the source assets require it. UI easing, tweening, and timeline behaviour can be implemented as domain/runtime components driven by Bevy time and systems; do not invent animation semantics that conflict with recovered UI or renderer handlers.

Cameras And Projection

Relevant features:

bevy_camera
bevy_camera_controller
free_camera
pan_camera
bevy_transform

Camera concepts and legal transitions should be domain-defined where they represent original game concepts: shell camera, world camera, panning, zooming, rotation, training/cinematic views, and selection focus. Bevy owns the live camera components/resources and implements the host view. Free/pan camera helpers are useful for development and may inform player controls only where they match recovered behaviour.

Devtools, Diagnostics, Gizmos, Remote, And Inspectors

Relevant features:

bevy_dev_tools
bevy_debug_stepping
bevy_diagnostic
sysinfo_plugin
bevy_gizmos
bevy_gizmos_render
bevy_remote
bevy_ui_debug
bevy_log
trace
trace_chrome
trace_tracy
trace_tracy_memory

Use diagnostics for frame time, asset loading, system cost, entity counts, terrain chunk rebuilds, UI dirty updates, draw-call pressure, memory use, and audio/asset queues. Gizmos should be standard for reconstruction debugging: camera frustums, placement grids, path/fence routes, terrain chunks, selection rays, AI targets, and nav/path queries. Keep remote/devtools in the development tooling surface.

Logging And Settings

Relevant features:

bevy_log
bevy_settings
sysinfo_plugin

Use logging for source loading failures, missing assets, contract mismatches, performance warnings, and validation diagnostics. Settings can back modern graphics/audio/input preferences only when mapped cleanly to original options or explicitly separated as host settings.

Windowing, Cursor, And Host Shell

Relevant features:

bevy_window
bevy_winit
custom_cursor
wayland
x11
web
webgl2
webgpu

Use Bevy windowing for fullscreen/windowed mode, resize handling, cursor projection, DPI handling, input capture, and platform backend selection. The original graphics options and startup/window behaviour define the domain contract; Bevy implements the host mechanics.

Scene, GLTF, Serialization, And Tooling Imports

Relevant features:

bevy_scene
scene
bevy_gltf
gltf_animation
bevy_world_serialization
serialize

Use scenes/GLTF for tooling, visual regression fixtures, converted inspection assets, or temporary developer views. The canonical game data path remains the original Z2F/source formats. World serialization can support debugging and test snapshots; original saves/packages remain their own compatibility surface.

Platform, CI, And Build-Time Features

Relevant features:

bevy_ci_testing
dev
dynamic_linking
hotpatching
embedded_watcher
file_watcher
asset_processor
reflect_documentation

Use these to speed development, CI, and introspection. Dynamic linking and hotpatching can shorten iteration but should not become assumptions in release behaviour. CI testing should exercise source loading, deterministic domain handlers, and representative Bevy app schedules without needing the full interactive shell for every check.

Source Documents

Source parsing should produce one compact representation of a document. The XML/BFXML model must preserve ordered mixed content and attributes while avoiding duplicate owned children, content, and text trees.

The near-term shape is:

pub struct DataNode {
    pub name: String,
    pub attributes: Vec<DataAttribute>,
    pub children: Vec<DataChild>,
}

pub enum DataChild {
    Element(DataNode),
    Text(String),
}

Convenience APIs can expose element_children() or text() views. They should not own a second recursive tree.

The fuller performance target is an arena/range representation:

struct BfxmlDocument {
    nodes: Vec<BfxmlNode>,
    children: Vec<BfxmlChild>,
    attrs: Vec<BfxmlAttr>,
    text: Vec<Arc<str>>,
}

Nodes refer to child and attribute ranges. That preserves source semantics, reduces allocation overhead, allows stable node ids, and gives UI/domain hydrators cheap references into the parsed document.

Asset Loading

The source-compatible path is:

ZT2 path -> mounted archive entry -> lazy bytes -> Bevy AssetLoader -> Handle<T>
domain-defined asset type -> Bevy AssetLoader -> Assets<T> -> Handle<T>

The runtime should avoid extracting every asset into a temp directory as the main architecture. A temporary extraction bridge may exist while loaders are being replaced. The final engine should use archive-backed asset readers and Bevy loaders for images, models, materials, audio, UI documents, and other decoded artifacts.

Domain records should store source ids, path ids, type ids, or asset ids. Bevy presentation should store cheap Handle<T> values. Bitmap/model/audio bytes should not be copied into every UI node, material, entity definition, or world instance that refers to them.

Loaded asset instances should live in Bevy asset storage or Bevy-owned runtime resources/components. A domain collection of loaded values is valid only when evidence shows an original-game manager owns that collection as gameplay state with special behaviour. Otherwise it is a duplicate asset store and should be moved to Bevy, replaced by handles/references, or deleted.

UI Runtime

The UI should be a data-authored structure with domain-defined runtime contracts and Bevy-owned live state/presentation:

UiDocument asset owns authored structure.
UiLayoutRegistry indexes document/node ids.
Bevy entity tree is spawned from source node ids.
Each UI entity carries:
  UiSourceNode { document_id, node_id }
  UiWidgetRuntimeState or a reference to domain widget state
  Bevy Node/Image/Text/etc. presentation components
Input converts Bevy Interaction -> original UI message/event.
Domain handlers mutate UI/app/runtime state.
Projection systems update only changed entities.

Clicking a button should not execute invented Bevy behaviour. It should dispatch the original UI message contract into domain code, then Bevy should reflect the result by changing visibility, text, images, layout state, cursor, audio, or other presentation components.

Use the Bevy entity tree as the projection cache. Prefer concrete lookup indexes such as UiNodeId -> Entity or AssetPathId -> Handle<Image> when they solve a specific runtime problem.

World, Terrain, And Simulation

World entities fit Bevy ECS naturally. Animals, guests, staff, placed objects, vehicles, and interactable world objects should be Bevy entities with domain-defined components and ids tied back to the original entity/type system.

Terrain should not be represented as one entity per tile. Terrain wants packed arrays, chunks, dirty regions, and generated mesh assets:

terrain/map source data -> Bevy terrain resources/chunks using domain-defined data
dirty chunk/region -> generated Bevy mesh/material update
camera domain state -> Bevy Camera transform/projection

Simulation systems should mutate domain components/resources directly in Bevy storage. Presentation systems should observe changes and update render/UI/audio components. This avoids the pattern of continuing to mutate a boot-time session graph after the domain has been published into ECS.

Runtime Memory Rules

Immutable authored data should be stored once and shared by id/handle:

archive index
parsed document arena
localization table
entity/type registries
material/model/audio metadata
mode/config registries

Mutable runtime state should be stored once in Bevy resources/components:

app lifecycle
active UI/widget state
mode/world/app state
entity instance state
AI task state
terrain edit state
camera/input state
economy/status/progression state

Presentation should be derived and dirty-updated:

Bevy UI entities
text/image/layout components
mesh/material handles
audio players/sinks
camera transforms
animation/particle projections

Transient caches are valid only when they are indexes, handles, generations, or dirty sets over one owner. They must not become a second truth:

allowed: UiNodeId -> Entity
allowed: Assets<ZT...> storing loaded source/domain value types
allowed: AssetPathId -> Handle<Image>
allowed: dirty terrain chunks
allowed: changed widget ids
not allowed: copied UI document tree with independent state
not allowed: domain-owned loaded document collections duplicating Assets<T>
not allowed: domain-owned asset registries or caches mirroring Bevy asset storage
not allowed: duplicated entity definition records in presentation code
not allowed: copied world object graph plus ECS object graph

System Connection Pattern

The bridge between source/domain and Bevy should be ordinary Bevy systems:

load source asset -> hydrate domain registry resource
input event -> domain message handler
domain state changed -> update presentation components
asset handle ready -> attach image/mesh/material/audio
simulation tick -> mutate domain components/resources

This gives the reconstruction Rust/Bevy performance while retaining the original game's source compatibility and semantic contracts. The original files and domain meanings stay canonical; the original C++ heap mechanics do not.