Thing/docs/world-state-lowering.md

Eve World-State Lowering

Date: 2026-07-07

Eve does not only lower interface widgets. Eve lowers authored surfaces that may include UI, live state pointers, commands, assets, 2D fields, 3D fields, entity/object rows, and native view descriptors. A provider may publish a surface for a compact dashboard, a browser canvas, a native mobile view, a desktop tool, a 2D tactical map, a 3D action-game scene, or a future room-scale projection. Those are different lowering targets for one semantic contract.

Authority

Provider owns:

• committed domain state;
• rules and accepted command effects;
• state pointers and document identities;
• authored surface semantics;
• assets and asset manifests;
• render-field documents and view descriptors when they describe provider state.

Eve owns:

• the portable surface contract;
• layout and interaction semantics;
• state-binding and operation-invocation semantics;
• modal/dropdown placement semantics;
• generic asset-reference lowering hooks;
• 2D and 3D scalar/vector/color field visualization primitives;
• native-view descriptor semantics;
• renderer parity expectations across runtimes.

Runtime lowerers own:

• native projection;
• input hardware capture;
• frame timing;
• local caches and native buffers;
• quality/performance choices that do not change provider meaning.

CultMesh owns:

• typed state delivery;
• subscriptions and replay;
• provenance;
• asset transport;
• operation routing.

No renderer gains provider authority because it can draw a provider surface.

World Surfaces

A world surface is an Eve surface whose retained tree describes a view into provider world state. It may contain normal UI controls, but it also carries instructions for reconstructing a spatial presentation.

World surfaces should be able to describe:

• state pointers to daemon/provider-owned typed documents;
• high-performance SoA or native-view descriptors;
• object/entity render rows with transforms, labels, selection metadata, and operation affordances;
• 2D scalar fields, such as height, influence, heat, pressure, or gravity;
• 2D vector/color fields, such as tint, fog, flow, current, or velocity;
• 3D scalar fields, such as density, temperature, or occupancy;
• 3D vector fields, such as flow, force, wind, or steering;
• field visualizers, such as isolines, shaded height, probes, volume slices, particles, streamlines, glyphs, or contour bands;
• render splat buffers and accumulation rules;
• asset refs for sprites, icons, meshes, materials, shaders, generated textures, and media;
• presentation-quality hints and level-of-detail policy.

The renderer chooses the best native projection it can support. It must not invent provider semantics to compensate for missing contract information.

Entity SoA Views

gamecult.eve.entity_soa_view.v1 is the portable descriptor for hot entity presentation state. A world.scene2d or world.scene3d component points to it with entityViewPointerId; entityViewSchema names the schema and entityBodyId names the stable logical hot body whose representations the client may demand. Body identity is provider-advertised contract state, not a provider-specific convention embedded in a lowerer. The surface does not duplicate entity transforms as retained child components.

World scenes may also publish generic presentation intent derived from provider state:

• cameraRig names the portable composition algorithm. For planar.top-down-follow.v1, the play plane is XZ and the perspective camera looks along negative Y;
• cameraTargetEntityId is the sole entity the active camera rig frames. A lowerer must not add combat selection, renderer bounds, or another implicit subject to that framing set;
• cameraDistance, cameraVerticalFieldOfViewDegrees, cameraTargetScreenX, cameraTargetScreenY, and cameraPositionDamping define the provider-owned lens and composition. Screen coordinates are normalized viewport coordinates with a bottom-left origin; damping uses the exponential response 1-exp(-damping*deltaTime);
• cameraNearClipPlane and cameraFarClipPlane complete the perspective lens contract. A lowerer must not substitute engine defaults that cull advertised world content;
• ambientLightColor and ambientLightIntensity define portable ambient illumination when the selected camera rig supports it;
• skyboxAssetRef optionally selects a provider-advertised material and reflectionAssetRef optionally selects a provider-advertised cubemap. Native Unity variants must resolve those exact references as Material and Cubemap respectively; an omitted reference requests no override for that part of the environment. reflectionIntensity scales the latter. Negative intensities clamp to zero; non-finite environment values invalidate the presentation contract. The active camera rig owns one reversible environment lease over the runtime's global lighting state and camera clear policy. A lowerer must reject a missing, incompatible, or unsupported advertised asset instead of substituting product-specific art;
• postProcessProfileAssetRef optionally selects a provider-advertised native post-processing profile variant. The logical reference is portable; each runtime resolves only its own compatible asset variant. A runtime that supports the selected variant leases the profile for the active world camera and restores its previous camera/post-processing state on disconnect or rig replacement. Missing, incompatible, and unsupported variants fail closed. Runtimes do not infer exposure, bloom, grading, or product identity from fog colors or provider ids;
• lookCommand accepts a controlled entity id and a unit directionX, directionY, directionZ vector. The provider remains the owner of the accepted look direction; runtimes only lower local pointing input into this intent. lookModel names the portable input geometry; planar-yaw.v1 rotates on the XZ play plane. lookSensitivityRadians optionally maps one native pointer-delta unit to yaw radians, including the provider-authored axis sign;
• subjectVisible controls presentation of playerEntityId without deleting that authoritative entity from the world view;
• movementEnabled controls whether the runtime emits movement intents;
• presentationMode names a portable state such as world or docked for runtime-quality choices that do not alter provider truth.

These values are presentation instructions, not gameplay state. A provider may derive them from docking, possession, spectating, incapacitation, cutscenes, or another domain rule. A lowerer must not import the provider's private document types to reconstruct them, and it must not treat hiding or camera retargeting as removal of the underlying entity.

A Unity scene has one active world environment owner. A lowerer that mutates scene-global render settings must restore the previous environment when its world disconnects, its rig changes, or the lowering component is disabled or destroyed.

An optional aim.presentation child binds presentation to that authoritative body direction without duplicating it. controlledEntityId identifies the body, convergenceTargetEntityId optionally names the selected body whose distance sets convergence, and minimumConvergenceDistance supplies the lower bound when there is no farther target. viewDotRole and viewDotRadius describe the portable marker. A lowerer must not steer weapons, tractors, or the body transform from the marker; it renders the direction committed by the provider's body publication.

An optional beam.presentation child binds a continuous provider-authored effect to an entity in the current SoA generation. It carries:

• sourceEntityId: the authoritative presented body that owns the effect;
• directionMode: the portable orientation rule. source-forward.v1 follows the source body's published forward axis and never writes that transform;
• assetRole: a semantic provider-manifest role used to resolve native art;
• power: a provider-owned non-negative bootstrap/fallback intensity value;
• powerStateSemantic: an optional float semantic in the source entity's hot SoA row. When present it is the live authority for power; the retained literal is bootstrap/fallback state only. This keeps continuous effects on the same negotiated body plane as their transforms;
• activationThreshold: the value below which emission is zero while the retained effect may finish its local particles;
• radius and maximumDistance: portable shape facts for lowerers that do not consume the provider's native effect asset;
• renderChannel: the semantic presentation channel, such as world.effects;
• activationActionId: an optional action from the advertised input capability that controls the effect. Generic clients may bind or invoke this action without knowing the provider's operation name.

Beam presentation is not a physics query. A lowerer must not raycast, apply force, infer a hit/contact, collect an item, or emit a gameplay receipt from the visual. Providers and their physics owner publish the state and contact facts; runtimes only reconcile the effect against the current SoA transform.

The descriptor carries buffer locations, semantic columns, dirty ranges, and render groups. CultMesh selects the buffer route: shared memory for co-located runtimes, a native stream for remote runtimes, or another advertised backend. Replacing the reactive descriptor publishes a new generation and lowerers apply only its dirty ranges. A backend location is transport data, not provider authority.

Stable composition, commands, and binding declarations may arrive in a bootstrap snapshot. Live entity generations do not. UI values bind to reactive typed documents named by state pointers. Versioned asset manifests are bootstrap state and their content-addressed artifacts are cached.

An exact entity subscription includes the view record, the logical body's stable latest-publication record, the supported body transports, and the consumer runtime identity. CultMesh combines actual peer locality with those capabilities to select shared memory for same-machine clients and a network body plane otherwise. No consumer fetches a second snapshot per generation, and a provider does not build an unrequested representation.

Provider advertisements attach the reusable boundary to world surfaces through surfaces[].worldInteraction. That block names:

• projectionKind: the generic world presentation role, not a game-specific rule name;
• stateSchemas: provider-owned state documents that describe the world;
• commandBoundary: the provider command route that receives interaction intents;
• receiptSchema: the provider-owned receipt document schema;
• loweringTargets: runtime families expected to consume the surface;
• ownership: the plain-language authority rule for state, assets, command acceptance, and receipts.

Conformance scenarios can require worldSurfaces[] entries and the parity harness checks them against the advertisement. This makes an interactive world surface portable without giving Eve or a runtime private Aetheria knowledge.

Runtime capability manifests answer the other half with worldSurfaceLowering[]. Each claim names a targetId, supported surface kinds, projection kinds, support level, evidence paths, and the ownership rule that the runtime lowers provider state without becoming provider truth. If a provider advertises a lowering target and no runtime claims it, conformance emits a capability gap instead of quietly pretending the engine exists.

Quality Tiers

A low-end or debugging renderer may lower a world surface into labels, simple icons, flat shaded fields, and command lists.

A browser renderer may lower the same surface into Canvas, WebGL, DOM overlays, or a mixed scene.

A Unity, Godot, Direct2D, Vulkan, Metal, or future native renderer may lower the same surface into engine-native meshes, materials, particles, UI panels, input affordances, and camera-relative overlays.

Those are quality tiers over one Eve surface. They are not separate provider contracts and they are not permission for a runtime to carry private domain logic.

Aetheria Conformance Example

Aetheria is the current pressure case for this contract.

The Aetheria daemon should publish the game state, rules, generated level, assets, operations, scalar/vector fields, object rows, and Eve surfaces needed to render both Starbridge RTS and ARPG views. Hermodr should carry provider documents without interpreting plugin semantics; the browser fields adapter should reconstruct the RTS view as part of the unspecialized Eve lowerer. Electron should render the same surface as the player-facing Starbridge shell. Unity should become an ARPG lowerer over the same kind of daemon-authored surface, and Godot should become the equivalent non-Unity ARPG conformance target.

Aetheria-specific examples:

• gravity is a 2D scalar field; isolines are one visualization, not the field;
• nebula tint is a 2D vector/color field accumulated from provider-authored splat rules;
• volumetric flow is a 3D vector field;
• planets, ships, stations, projectiles, labels, and command affordances are object/entity render rows with provider-advertised assets;
• icons, sprites, materials, meshes, and generated textures resolve through CultMesh CDN refs.

If a renderer must know the phrase "Aetheria gravity" to draw the field, Eve is missing a generic scalar-field primitive or the provider surface is underspecified. If a renderer must know "Aetheria planet" to draw a body, the object row or asset contract is underspecified.

The incubating Aetheria fixture advertises aetheria.daemon.game as interactive-world with worldInteraction.projectionKind: provider-authored-world-surface, commandBoundary: aetheria.daemon.commands, and receiptSchema: aetheria.eve_command_acceptance_status.v1. Web, Unity UI Toolkit, Unity scene, Electron shell, and TUI lowerers are lowering targets; Aetheria remains the owner of world state, assets, command acceptance, and receipts.

The Unity scene lowerer now has a playable-world extraction and client-session proof. The fixture carries a generic world.scene3d node with a daemon state pointer, asset manifest ref, third-person input/camera profile, movement/focus/target command names, world.entity3d rows, and a field.vector3d volume field. The Unity scene runtime lowers that into playableWorld projection evidence: entity ids, kinds, labels, positions, radii, asset refs, controllability, and command affordances. The generic EveUnitySceneClientSession consumes provider surface snapshots and emits gamecult.eve.command.v1 intents through the advertised command boundary. EveUnitySceneProviderConnection adds the live-source port shape: IEveUnitySceneProviderSurfaceSource supplies current and updated snapshots, while IEveUnitySceneCommandSink receives command envelopes. IEveUnitySceneProviderSurfaceDocumentSource, EveUnitySceneProviderSurfaceDocument, and EveUnitySceneProviderSurfaceDocumentSource now make that snapshot source a typed document-consumer boundary: a CultMesh/CultCache adapter can own surface delivery and publish provider-authored documents, while EveUnity only converts them into snapshots for the generic lowerer. EveUnityPlayableWorldLiveClient composes that connection with the playable world presenter: every provider snapshot is lowered into a presentation pass, Unity input still emits provider-owned command intents rather than mutating local world truth, and IEveUnitySceneCommandReceiptSource reports provider receipts as derived command status. Pending receipts do not move the scene; accepted or reconciled receipts only trigger a refresh from the provider surface source, so the next presentation still comes from daemon-authored state. EveUnityPlayableWorldRuntime is the generic runtime composition entry point: it wires provider surface documents, provider asset manifest documents, command sink, optional receipt source, asset manifest cache, presenter, and scene sink into one Unity playable-world client without importing provider code. The Aetheria provider bridge now implements the same receipt-source port: when the daemon accepts a surface command envelope or routes a fallback Eve command, it publishes an EveUnitySceneCommandReceipt through IEveUnitySceneCommandReceiptSource so the Unity client observes provider acceptance without mutating scene truth locally. EveUnityPlayableWorldPresenter maps the provider-authored entity rows and asset refs into scene operations through IEveUnityPlayableWorldSceneSink and IEveUnityPlayableWorldAssetResolver, including removal of entities that disappear from later provider snapshots. EveUnityGameObjectPlayableWorldSceneSink is the first Unity-native implementation: it creates or updates generic GameObject instances, applies transforms/radii, attaches an EveUnityPlayableWorldEntityMarker, and resolves provider asset refs through an IEveUnityGameObjectAssetProvider hook. EveUnityPlayableWorldAssetManifest and EveUnityManifestGameObjectAssetProvider add the provider-manifest mapping step: provider asset refs and entity kinds become Unity resource/prefab keys through data rather than Aetheria code. gamecult.eve.unity_playable_world_asset_manifest.v1, IEveUnityPlayableWorldAssetManifestDocumentSource, and EveUnityPlayableWorldAssetManifestDocumentSource define the typed document loading boundary for those Unity load keys. IEveUnityPlayableWorldAssetManifestSource and EveUnityPlayableWorldAssetManifestCache key live manifest updates by the playableWorld.AssetManifest pointer, so a CultMesh/CultCache source can update Unity asset bindings without changing the lowerer. EveUnityLivePlayableWorldAssetProvider connects that cache to the active world pointer for GameObject scenes. Aetheria-specific names appear only as provider-authored data and command ids; the Unity client code does not import Aetheria runtime types, prefab classes, or apply movement locally.

This is not yet the final playable client. The Aetheria consumer bridge now feeds surface documents, asset manifest documents, command submission, and provider receipts into the generic Unity ports. The remaining cut is live CultMesh/CultNet subscription ownership for those same ports and proof that daemon receipts plus refreshed provider documents drive the next rendered Unity frame rather than renderer-local state.

Non-Goals

Eve does not own provider gameplay rules.

Eve does not require every renderer to reach the same visual sophistication.

Eve does not collapse every engine into one rendering backend.

Eve does not turn native runtime caches into provider truth.

Eve does define enough shared semantics that provider-authored world surfaces can be reconstructed across runtimes without provider-specific renderer brains.