EveUnity/packages/org.gamecult.eve.unity-scene

Eve Unity Scene Lowering

Provider-agnostic Unity scene lowering for gamecult.eve.surface.v1 interactive worlds.

Providers implement the surface-document, asset-manifest, command-sink, and receipt-source ports. EveUnityPlayableWorldClientBootstrap wires those ports to the generic scene host, input driver, camera rig, GameObject sink, and UI Toolkit surface overlay. The overlay lowers provider-owned panes, metrics, progress, inventory, and controls from the same Eve document used by the scene. Stable structures update their native controls in place; only structural changes rebuild the visual tree. Scene, field, and reactive render subtrees are owned by their native lowerers and are not duplicated into empty UI elements.

EveUnityCultMeshPlayableWorldProvider is the runtime composition root for a networked client. Give it one Verse rendezvous endpoint and it discovers an advertised interactive-world, constructs the generic CultMesh transport, and provides every bootstrap port. Provider, surface, and Verse IDs are optional selection filters; they are not product knowledge required by the client. The selected Verse ID and its advertised authority-runtime ID form the stable CultMesh session target. The Eve provider ID separately names the UI owner found through that target. Physical routes are resolved and re-resolved inside CultMeshClient; they are never published as provider selection state or cached as Unity authority. The optional local path is only an ephemeral content/body cache, not a replicated gameplay database. Await PrepareAsync() before mounting the bootstrap or reading provider ports. It owns discovery, initial document reads, content transfer, asynchronous asset bundle loading, and live lease installation. Once preparation succeeds, Mount() and Connect() perform no remote work. Input submission only enters a bounded asynchronous outbox: one-shot commands retain their idempotency keys, while movement and look values coalesce to the latest value per entity. A successful send is not completion: the command remains pending and retries with the same idempotency key until its canonical provider receipt arrives. Failed or unacknowledged commands rotate behind other due work, so one poison command cannot starve the outbox. Live entity, field, and receipt polling likewise remains non-blocking. Unity's main thread applies completed typed documents and assets; it never waits for a CultMesh task, keeping Play, Pause, input, inspection, and rendering responsive while a provider is slow or temporarily unreachable.

An Eve world may qualify its asset catalog with a different provider, Verse, authority runtime, and Odin rendezvous set than the surface provider. The transport resolves that exact asset session and commits assets as one generation: catalog, verified bundles, leases, lookups, render policy, and surface lowering are prepared off to the side, then swapped together. A failed or superseded candidate is disposed without unloading or rewriting the mounted generation. The mounted provider's trust policy authenticates only that provider. A provider-qualified asset source in another Verse/runtime uses the configured cross-target Odin trust for its catalog, subscription, manifests, content, and bundles; local-development trust does not cross that boundary. The candidate opens its catalog lease before preload, observes updates in a candidate-owned buffer, and verifies the leased version again before commit. An update that lands during preload therefore rebuilds the candidate instead of disappearing between a one-shot read and a later subscription.

Navigation keeps the outgoing presentation quiesced until the candidate route is ready, then commits the provider route before activating the candidate. Presentation connections are provider-owned leases: disposing the outgoing host releases only its lease and cannot disconnect the newly committed Verse.

The package never imports provider product assemblies.

Add EveUnityRendererFeature to the Universal Renderer used by Eve cameras. The feature is the single URP-owned scheduling point for provider-advertised volume, particle, and exposure programs. The lowerers use Unity 6 RenderGraph resource declarations; effects that sample camera color request an intermediate color texture and never read the back buffer. Do not schedule these effects from RenderPipelineManager callbacks. The provider owns programs, assets, and parameters; the Universal Renderer owns when and where they execute. Provider volume programs render through both Game and SceneView cameras. Each camera owns separate raymarch and temporal-history targets, so editor preview cannot resize or contaminate the playable camera's history. Presentation-only exposure remains bound to the leased Game camera.

Advertised input bindings are performed from the provider's semantic action catalog. Direct and chord gestures submit once per press edge; held values submit their advertised press/release scalar. view-direction.v1 samples the active world camera's normalized world-space forward direction into the three advertised payload keys. Providers own what that ray means; EveUnity never selects targets or imports provider gameplay policy.

EveUnityInputActionBar lowers provider suggestions and profile-visible actions from that same catalog. It resolves iconRef through the provider asset manifest, disables unavailable actions, preserves press/release behavior for held controls, samples the active camera for view-direction controls, and submits scalar.v1 values from an explicit numeric field. Its named UI Toolkit elements and classes are presentation levers; the component never imports a provider assembly or mutates provider-owned current values optimistically.

IEveUnityPresentedEntityRegistry exposes each committed SoA generation as immutable entity facts plus presentation transforms, addressable by Eve entity id or source index. Camera, selection, and provider UI adapters consume that registry instead of reconstructing provider gameplay objects. It owns presentation lookup only; simulation state and commands remain provider-owned.

World surfaces may exclude semantic render channels through the excludedRenderChannels world-root property. Runtime asset variants map those channel names to Unity layers with renderChannel.<channel>.unityLayer metadata. Surfaces never publish Unity layer numbers or camera masks: providers own which semantic content belongs in a view, while EveUnity owns the native layer mapping and subtracts only those layers from the camera's configured culling mask.

World surfaces may also advertise a presentation-only directional key light through keyLightDirection, keyLightColor, and keyLightIntensity. EveUnity lowers those generic values into a transient Unity light and removes it when the world camera lease ends. The provider owns the lighting design; the light never becomes physics, visibility, or gameplay authority.

Retained provider feedback is lowered without becoming Unity authority. EveUnityFeedbackPresenter emits each new feedback.event identity once, and EveUnityShotReceiptPresenter does the same for shot.receipt trajectories. The generic EveUnityShotTrajectoryRenderer renders provider-authored origin, endpoint, duration, and hit outcome, then expires the visual locally. It never uses Unity collision to infer damage or report a hit back to the provider. Providers may publish a non-spatial combat.presentation component beside the SoA body view. EveUnityCombatPresentationRenderer lowers its selected target, contact visibility, lock progress, meter ratios, semantic roles, and timing into reticle, lock, shield/hull, and hit-marker visuals. Hit markers require a new deduplicated shot receipt from the advertised controlled source to the advertised selection with authoritative applied or shield-absorbed damage. SoA remains the only transform authority; the presentation component never duplicates bodies or computes combat outcomes. Continuous beam.presentation nodes bind provider-authored effect assets to the current presented-entity generation. The generic beam renderer follows the advertised source transform, applies provider-owned power to particle emission, and reconciles asset lifecycles by semantic role. It never raycasts, applies force, infers contact, collects cargo, or emits gameplay receipts. The reusable LightningCompute renderer and its shader/material bundle live in this runtime package with their original Unity GUIDs. Provider asset bundles may therefore reference the effect without importing Aetheria gameplay code.

fields.surface projection consumes the plugin-owned org.gamecult.eve.plugin-fields contracts. EveFieldsSplatRasterizer owns the Unity structured-buffer and RenderTexture lowering without importing provider document classes.

field.volume3d surfaces name logical texture ports, feature names, quality, and authored scalar/vector parameters. Concrete Unity shader properties, keywords, and pass indices belong to the selected unity-scene asset variant under unity.volume.* metadata. The lowerer fails closed when that native program descriptor is absent or incomplete. This keeps provider shader ABIs out of Eve's semantic surface while allowing a provider-owned shader to consume portable Eve Fields documents. Volume composition runs as a generic URP render pass before post-processing so the provider-advertised profile grades both the native scene and the provider volume through the same camera pipeline.

Camera-relative field consumers share viewportAnchor, span, cellWorldSize, viewportSnapLayer, and viewportSnapTexels as one viewport frame contract. Volume and particle lowerers resolve that frame through the same generic path, so a snapped stateless particle lattice cannot drift from the field textures it samples. A world.scene3d may also request temporal-reprojection.v1; EveUnity lowers its neutral history blend, jitter, quality, and sharpening values to URP TAA and restores the previous camera state when the world releases the camera.

Native volume programs also advertise the projection convention consumed by their history matrix. non-render-target-projection.previous-view.v1 preserves the projection convention used by legacy Graphics.Blit temporal shaders even when EveUnity executes the program through a render-target-backed URP pass; providers must not rely on a runtime guessing that Y-axis convention.

field.particles3d may advertise provider material textures, viewport-relative texture scales, and a logical render-frame index port. These are presentation inputs: EveUnity binds the selected provider assets and current display frame without assigning product meaning to the shader. Stateless simulation time and particle positions remain provider-document inputs.

Providers may advertise per-layer resolution scales, mipmap use, and filtering through layerTargetDescriptors; the Unity lowerer applies those native target requirements without assigning gameplay or product meaning to the layer keys. documentFloatBindings maps standard document scalars to logical float ports as source=port,scale,offset. This lets animated native programs consume provider-authoritative simulation time without making the client clock an authority. Native volume programs may advertise a cameraToWorld matrix port when their procedural passes require an explicit camera transform instead of relying on render-pipeline globals.

Command finality is presentation-causal. When a terminal receipt names a sourceVersion newer than the mounted surface, EveUnity keeps the command and its exact receipt lease alive, makes the obsolete surface read-only, and emits the terminal receipt only after that surface generation and its qualified asset catalog have committed together. Asset preparation failure therefore cannot leave an accepted Verse switch paired with actionable controls from the prior Verse. Embedded surfaces may recompose the visible tree, but their versions are derived rendering inputs and cannot satisfy or clear the advertised base surface's finality barrier.