Asset conversion lineage

Every accepted original format, its offline transformation, native extension, mapped ownership, and final Bevy or renderer handoff. Source archives stop at preflight; the game opens only the resolved .ozp profile.

Mapped custom assetsAll immutable archives remain ranges inside one Arc<MappedPack>. Bevy handles point to custom asset wrappers over those ranges.

Bevy-native zero-copyNone of Bevy’s stock payload assets currently borrow arbitrary mmap ranges. Where payload borrowing matters, OpenZT2 supplies the custom asset and preparation path.

Owned preparationOnly bounded metadata, decoder state, ECS components, or GPU resources are created. Payload-sized CPU Vec copies are limited to decoded video frames and save snapshots.

Family	Original extension / input	Preflight transition	Native extension and rkyv root	Resolved profile	Bevy asset boundary	CPU ownership after load	Final handoff
Container	`.z2f` (ZIP)	central directory → normalize paths → later archive wins → inflate winner only	`.ozp` PackHeader + sorted catalogue	Page-aligned winning payloads and typed bindings	`Arc<MappedPack>` shared by custom Bevy loaders	mmap borrow No decoded copy	Allocation-free catalogue lookup
Persistence	`.z2s` original save	runtime boundary; never accepted as preflight content	`.ozs` OpenZT2 snapshot	Outside `.ozp`	Persistence systems, not a Bevy content asset	owned Vec Explicit save/load snapshot	ECS snapshot application
UI	`.xml` `.maxml` `.zt2` `.trk` `.old`	BFXML repair → semantic classification → widget, style, command and reference binding	`.ozui` UiArchive	Flat nodes, child ranges, strings, bindings and dependencies	`UiDocumentAsset` (custom Bevy Asset)	mmap borrow No second document tree	Ordinary Bevy UI entities/components
Localization	`.xml` `.maxml` `.zt2`	decode → merge locale fragments → resolve fallback order	`.ozloc` LocalizationArchive	Sorted keys and string ranges	`LocalizationAsset` (custom Bevy Asset)	mmap borrow	Borrowed localized strings
Behavior	`.tsk` `.beh` and behavior XML	compile task sets, subjects, callbacks and typed operations	`.ozbehavior` BehaviorArchive	Task tables, subject joins and operation streams	`BehaviorProgramAsset` (custom Bevy Asset)	mmap borrow	Focused ECS behavior systems
World data	`.xml` `.maxml` `.zt2`	resolve inheritance, managers, catalogues, placeables and gameplay definitions	`.ozdefs` WorldDefinitionsArchive	Consumer-shaped flat definition tables	`WorldDefinitionsAsset` (custom Bevy Asset)	mmap borrow	ECS spawn and domain systems
Scenarios	`.xml` `.maxml` `.zt2`	compile campaigns, maps, objectives, rewards and scenario operations	`.ozworlds` WorldScenarioArchive	Scenario and map tables	`WorldScenarioAsset` (custom Bevy Asset)	mmap borrow	Scenario lifecycle ECS systems
Species	`.xml` `.maxml` `.zt2`	compile species, needs, compatibility and authored defaults	`.ozspecies` SpeciesArchive	Sorted species and relationship tables	`SpeciesCatalogAsset` (custom Bevy Asset)	mmap borrow	Animal prefab and lifecycle systems
Lua	`.lua`	parse supported Lua 5.0 source → typed behavior or scenario operations	`.ozbehavior` or `.ozworlds`	Operation streams joined to their authoritative owner	Owning mapped behavior/scenario asset	mmap borrow No runtime Lua VM	Focused ECS systems
Lua residue	`.bin` compiled Lua twin	validate against source twin → omit	—	Not packed	—	omitted	Source-authored typed operations win
Schemas	`.xdr`	validate tooling schema → omit from runtime	—	Not packed	—	omitted	Preflight validation only
Launcher	`.dl`	read launcher metadata only → omit	—	Not packed	—	omitted	Preflight UI metadata
Models	`.nif` `.bfb`	parse block graph → resolve hierarchy, materials and skeleton → write GPU vertex/index tables	`.ozmodel` ModelArchive	GPU-ready vertex/index/meshlet ranges plus draw metadata	`ModelAsset` → custom `GpuModelAsset`	mmap borrow Small boxed draw metadata only	One upload to wgpu buffers; no CPU `Mesh`
Scenes	`.nif` `.bfb`	flatten authored prefab hierarchy and dependencies	`.ozscene` ScenePrefabArchive	Flat entities, child ranges, attachments, colliders and renderables	`ScenePrefabAsset` (custom Bevy Asset)	mmap borrow	Bevy entities and small components
NIF materials	`.nif` embedded properties	lower each geometry’s resolved render properties and texture references	`.ozmaterial` MaterialArchive	Deterministic per-geometry material records	`MaterialAsset` → custom `GpuMaterialAsset`	mmap borrow Small uniform/IDs prepared	wgpu uniform and texture bind groups
Rigging	`.nif` `.bfb` skeleton data	resolve joint order, inverse bind pose and skin weights into model contract	`.ozmodel` ModelArchive skeleton tables	Skeleton identity also keys animation binding catalogue	`ModelAsset` plus ECS `SkinnedPose`	mmap borrow Pose buffer is bounded owned state	Skinned render shader
Animation	`.bf` `.kf`	parse clips/controllers → join to resolved skeleton → quantize key tables	`.ozanim` AnimationArchive	Tracks, keys, clips and skeleton binding	`AnimationAsset` (custom Bevy Asset)	mmap borrow Bounded pose scratch only	ECS animator sampling → skin palette
Animation graph	`.bfm`	compile graph, transitions, sequences and clip references	`.ozanim` AnimationArchive graph tables	Graph data co-located with clip contract	`AnimationAsset` (custom Bevy Asset)	mmap borrow	ECS animation graph state
Animation events	`.txtkeys`	parse authored key events → compile sorted marker table	`.ozanim` AnimationArchive event tables	Markers share clip identity	`AnimationAsset` (custom Bevy Asset)	mmap borrow	Bevy animation messages
Animation residue	`.kfm` `.kfinfo` `.bip`	validate exact authored residue and preferred same-stem source → omit	—	Not packed independently	—	omitted	Resolved `.ozanim` owns behavior
Materials	`.bfmat`	parse parameters → resolve textures, modes and fixed-function render state	`.ozmaterial` MaterialArchive	Flat parameters, texture IDs and render state	`MaterialAsset` → custom `GpuMaterialAsset`	mmap borrow Tiny uniform/ID arrays prepared	wgpu pipeline and bind groups
Shaders	`.fx` `.h`	parse supported technique vocabulary → validate variants → compile GPU modules	`.ozshader` ShaderArchive	Preflight-produced module bytes and variant tables	`ShaderAsset` (custom Bevy Asset)	mmap borrow	Borrow module bytes for pipeline creation
Effects	`.fx` `.h` `.psys`	compile emitters, modifiers, curves, clocks and dependencies	`.ozeffect` EffectArchive	Flat effect tables	`EffectAsset` (mapped) → Bevy Hanabi assets	bounded Vec Hanabi graph/modifiers once; payload stays mapped	Bevy Hanabi particle simulation/rendering
Textures	`.dds`	translate identifiers → validate authored mips → preserve compatible BC blocks; convert only unsupported branch	`.oztexture` TextureArchive	Tight GPU subresources; no pad/unpad cycle	`TextureAsset` → custom render preparation → Bevy `GpuImage`	mmap borrow No Bevy `Image.data` copy	One upload from `&[u8]` to wgpu texture
Textures	`.tga` `.bmp` `.jpg` `.jpeg` `.cur`	decode offline → generate mips only when absent/invalid → encode target-native GPU format	`.oztexture` TextureArchive	Tight GPU subresources	`TextureAsset` → custom render preparation → Bevy `GpuImage`	mmap borrow No decoded runtime image Vec	One upload from mapped bytes
Image residue	`.psd`	not an original runtime loader input; audit and omit	—	Not packed	—	omitted	No runtime path
Audio	`.wav` `.wave`	decode offline → small resident PCM16 or large streamed Vorbis according to usage policy	`.ozaudio` AudioArchive	PCM or encoded stream payload with timing/loop metadata	`AudioAsset` + custom Bevy `NativeAudioSource`	mmap borrow Decoder cursor owns no payload copy	Bevy AudioPlayer / rodio decoder
Audio	`.mp3`	validate headers, duration and loop policy → retain authored MP3 bytes	`.ozaudio` AudioArchive	Authored MP3 stream plus metadata	`AudioAsset` + custom Bevy `NativeAudioSource`	mmap borrow	Bevy AudioPlayer / rodio MP3 cursor
Audio metadata	`.gpk`	parse envelope → resolve owning encoded clip, cues, aliases and stages	`.ozdefs` audio corpus tables + referenced `.ozaudio`	Associations only; duplicate envelope bytes omitted	Mapped definitions and audio handles	mmap borrow	Audio cue ECS systems
Video	`.bik`	FFmpeg/libav demux and decode → colour conversion → native AV1 packets	`.ozvideo` VideoArchive	Blocked until approved Bink frontend/backend is installed	`VideoAsset` + bounded decoder pool	decoded Vec Reused frame slots only	Reusable Bevy GPU images
Terrain	`.dat`	parse height/cell data → orient units → compile tiles, layers, water and bounds	`.ozterrain` TerrainArchive	Flat terrain chunks and GPU ranges	`TerrainAsset` (custom Bevy Asset)	mmap borrow	Terrain entities, sampling and renderer upload
Navigation	`.dat` plus resolved world definitions	derive immutable navigation topology offline	`.oznav` NavigationArchive	Compact cells, links and lookup ranges	`NavigationAsset` (custom Bevy Asset)	mmap borrow Per-agent routes are bounded ECS state	Locomotion/pathfinding systems
Residue	`.txt` `.corelog` `.bat` and extensionless entries	audit corpus role → omit when no original runtime owner exists	—	Not packed	—	omitted	No runtime path
Fonts	OS font API; no archive extension	resolve recovered alias, size and fallback policy	External boundary; no invented font archive	Not packed as source content	Ordinary Bevy text/font and glyph-cache path	Bevy owned Platform/font cache data	Bevy text renderer

Custom Bevy Asset borrows mapped rkyv bytesBevy-native ownership/handoffBounded owned preparationValidated then omittedBlocked route

The Vec fields visible in converter-side Rust structures are archive-construction inputs. After rkyv serialization they are archived vectors traversed in place; they are not reconstructed as runtime heap vectors. Small handle arrays, draw metadata, pose buffers, decoder state, and GPU objects are deliberate runtime state rather than copies of source payloads.