erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
acdream/docs/research/2026-07-31-canonical-set-position.md

18 KiB
Raw Blame History

Canonical retail SetPosition — placement/streaming Slice 4A

Scope

This note pins the pure physics half of the placement/streaming closeout. Slice 4A lands the retail placement transaction as a separately testable Core mechanism. It deliberately does not replace the production snap-only resolver yet: Runtime lost-cell ownership and the complete inbound-route cutover remain Slice 4B. AP-1 and AD-1 therefore remain active until that cutover is complete.

Named-retail oracle, Sept 2013 EoR:

  • CPhysicsObj::SetPosition 0x005160C0
  • CPhysicsObj::SetPositionInternal 0x00515BD0
  • CPhysicsObj::AdjustPosition 0x00511D80
  • CPhysicsObj::CheckPositionInternal 0x00511E90
  • CTransition::find_valid_position 0x0050C310
  • CTransition::find_placement_position 0x0050C170
  • CTransition::find_placement_pos 0x0050BA50
  • CTransition::validate_placement_transition 0x0050ADC0
  • CTransition::validate_placement 0x0050B210
  • CPhysicsObj::ForceIntoCell 0x00515660
  • CPhysicsObj::handle_all_collisions 0x00514780

Retail transaction

SetPosition(request):
    transition = makeTransition()              // GENERAL_FAILURE if none
    init_object(transition, object)

    if the PartArray has no spheres:
        init_sphere(1, dummy center=(0,0,0.1), radius=0.1, scale=1)
    else:
        init_sphere(first min(count,2) authored spheres, exact object scale)

    if flags & RANDOM_SCATTER (0x200):
        return scatter only

    result = SetPositionInternal(request)
    if result != OK and flags & SCATTER (0x100):
        return scatter
    return result

SetPositionInternal(request):
    AdjustPosition(request frame, first sphere, noCreate=(flags & 0x20))
    if no resident cell:
        store the adjusted authoritative frame and enter lost-cell lifetime
        return OK

    if the live weenie is Hook, Storage, or Corpse:
        return ForceIntoCell(resident cell, frame)

    set do_not_load_cells from flag 0x20
    if !CheckPositionInternal(...):
        handled = handle_all_collisions(...)
        return handled ? COLLIDED : NO_VALID_POSITION
    if transition.curr_cell == null:
        return NO_CELL
    commit the complete transition
    return OK

AdjustPosition branches on the claimed cell shape. A direct outdoor claim runs pure LandDefs::adjust_to_outside normalization before visible-cell lookup. An indoor claim first resolves the visible cell and child; only a resident indoor cell marked seen_outside falls back to outdoor normalization. An absent indoor cell (including the 0xFFFF sentinel) remains the exact claimed cell/frame. A map-edge outdoor normalization failure stores cell zero with the otherwise unchanged frame. The old max(terrainZ, z) lift and nearest-in-Z scan do not occur in this canonical mechanism.

CheckPositionInternal calls the complete placement transition. Without the slide flag, retail accepts the result only when signed resolvedX-requestedX <= 0.0500000007, the same signed Y condition holds, and the cell is unchanged. Z is not part of that predicate. The resolved origin is accepted while the requested orientation remains intact.

Two validators, not one

The similarly named retail helpers have different contracts and stay separate in the port:

  • validate_placement_transition is the inner find_placement_pos validator. Any non-OK state from COLLIDED through SLID, when sliding is permitted, resets COLLISIONINFO; it never retries placement.
  • validate_placement is the outer initial/final validator. Only ADJUSTED or SLID, and only while its retry argument is true, performs one placement_insert; COLLIDED neither resets nor retries.

Step-down is disabled only for missiles. For fewer than two spheres retail first clamps the requested height to half the radius when the sphere diameter is less than or equal to that height. It then performs one full probe when the diameter is greater than the resulting height, otherwise two half probes. Equality belongs to the two-half-probe branch.

Modern seam

PhysicsEngine.SetPosition returns one immutable PhysicsSetPositionResult. SetPositionError retains the header values (OK=0, GENERAL=1, NO_VALID=2, NO_CELL=3, COLLIDED=4, INVALID_ARGS=0x100) while PhysicsResidenceDisposition separately reports Committed, DeferredCell, or Unchanged. Missing content is therefore successful-but-deferred, never misreported as a placement failure.

The result carries the complete commit packet: root/cell-local frame, contact/walkable/water state, sliding and collision normals, stationary-fall counter, a complete immutable COLLISIONINFO snapshot for the real handle_all_collisions callback (including contact/last-contact, sliding, collision normal, stationary-fall, environment, adjustment, and object fields), the callback result, and an explicit shadow action. A PhysicsBSP or changed-cell force commit requests canonical shadow recalculation; a non-BSP transition replaces its shadows only when the transition produced a nonempty cell array, otherwise it preserves the prior list. Unchanged force placement changes only the frame.

Core never creates cells synchronously, so retail flag 0x20 (DoNotCreateCells) has no differential loader branch inside this pure mechanism. Both flag states can only observe already-published immutable cell content and otherwise return DeferredCell. Carrying the flag into exact-cell, generation-scoped async admission is part of the still-open Slice 4B adaptation tracked with AD-2; this slice does not claim a dead SpherePath field as exact behavior.

The existing public Resolve compatibility entry remains entirely unchanged for production movement and zero-delta callers. Its result cannot represent a successful-but-deferred residence, so hiding DeferredCell inside ResolveResult.Ok would corrupt the contract. Slice 4B will route every authoritative placement family through SetPosition, atomically install its packet, and own exact lost-cell wakeup/commit.

Automated oracle

PhysicsSetPositionTests pins error values, absent/invalid outdoor and indoor claims, cross-landblock frame normalization, map-edge failure and the 0xFFFF sentinel, dummy/authored sphere setup, nonpositive scale, Ethereal seeding, explicit-only PathClipped, missile step-down, exact equality schedules, both validators, the late compass sample's float bits, signed no-slide behavior, actual collision-handler mapping, force-class policy, explicit shadow actions, null current-cell wakeup, ten-record scratch exhaustion, exact scatter ordering, failed-probe scratch lifetime, and deferred-scatter stop. The legacy public Resolve fixture remains unchanged until Slice 4B.

Slice 4B1 — Runtime residence owner

Slice 4B1 adds the presentation-independent half of the cutover without changing a production graphical route yet. RuntimeSetPositionState accepts an exact entity/position token before graphical DAT preparation, consumes the immutable Core result, and commits body, contact, full cell, shadows, object clock, and Runtime spatial worksets before publishing one ordered placement delta. The delta carries the exact RuntimeEntityKey, session lifetime, position/spatial/placement versions, adjusted cell, collision generation, and optional portal-authority shape. A throwing or unavailable host does not roll simulation back: Runtime republishes the same projection token until the exact FIFO head is acknowledged. A newer operation changes an already- published token to Discard and increments its projection revision, so an acknowledgement of the previously observed Place/Withdraw cannot consume an unseen Discard. It is never silently forgotten. An unacknowledged lost-cell Withdraw transfers intact to a replacing accepted operation and remains the FIFO head before that replacement may publish Place.

The successful missing-cell path owns retail's residence shape:

SetPosition -> OK + DeferredCell
    retain adjusted Position and the same PhysicsBody/components
    clear only Active and suspend the object clock
    withdraw Runtime spatial worksets and shadow rows
    retain shadow registration and exact authored mover request
    append parentless root to (exact cell, collision generation)
    arm independent exact-key 25 s deadlines for root + direct children
    publish Withdraw

exact cell generation resident + Withdraw acknowledged
    re-run SetPosition with retained authored spheres and CurrentCellId=null
    atomically install complete result
    publish Place

Lost-cell membership buckets use retail-shaped append plus swap-remove. Destruction deadlines use an exact-key hash plus a bounded indexed min-heap, the allocation-bounded modern equivalent of retail's hash + PQueueArray<double> priority owner. Rearm/removal updates the exact heap node; there are no stale tombstones. Only committed, current direct children from the parent-incarnation ordered CHILDLIST participate; unresolved or future relations cannot inherit a deadline. Parent, pickup, delete, GUID replacement, newer Position, reset, and disposal cancel the exact incarnation and use leave-world semantics rather than a wakeable lost entry. The dormant collision-retirement entry parks non-static parentless indoor roots and, for complete withdrawal, affected outdoor roots. It performs a complete preflight and rejects overlap with any active accepted/host-ack-pending placement before mutating one resident. It then installs every affected canonical lost residence and operation before publishing the first synchronous Withdraw, so an observer re-entering for a later root inherits that root's exact pending Withdraw instead of having its newly accepted placement cancelled by the retirement loop. 4B2 must quiesce that placement prefix before invoking the entry in the same transaction that installs host acknowledgements.

Runtime retains the last accepted prepared mover request, including exact off-center/two-sphere payloads, scale, flags, and step values. A cold resident with no prepared request still withdraws atomically but remains explicitly in AwaitingPreparation; it cannot wake through an invented empty-sphere shape. Preparation is cached only after Core accepts it as Committed or DeferredCell. A rejected/malformed preparation keeps the same accepted token retryable and cannot replace the last validated mover used by later collision retirement. Runtime's host boundary rejects only non-finite consumed frame/shape values; retail-valid oddities such as nonpositive authored scale remain untouched. Likewise, a non-deferred wake failure retains the withdrawn body, independent 25-second lifetime, and exact operation: invalid arguments return to AwaitingPreparation and re-index for the next exact generation, while other world-placement failures also re-index. The last successful DeferredCell result and adjusted frame remain canonical across the failed attempt. No failed wake can leave a live entity withdrawn without a Runtime owner. The graphical/no-window cutover in 4B2 supplies that exact preparation token.

Retail CPhysicsObj::SetPositionInternal (0x00515BD0) calls prepare_to_enter_world (0x00511FA0) only when this->cell == 0. Consequently the physics update_time (PhysicsBody.LastUpdateTime) and active bit are reset only on the cellless-to-world edge. Ordinary same-cell or cross-cell in-world SetPosition preserves the already-consumed physics clock; entering the lost-cell residence also preserves it until the eventual cellless wake commit. Runtime pins both sides and does not inherit the older graphical teleport helper's unconditional timer reset.

The wake timestamp is in the Runtime simulation-time domain, never Unix/UTC: GameRuntime binds its instance GameRuntimeClock through the entity/physics owner, and RetryDeferred samples SimulationTimeSeconds. Standalone Runtime fixtures without a bound game clock retain the accepted command time. This is a Runtime dependency only; no App delegate enters the owner.

The canonical commit also installs every SetPosition-derived body invariant before host publication: Contact/OnWalkable/WaterContact, the current contact plane and slope GroundNormal, Sliding plus its normal, and the complete StationaryFall/Stop/Stuck encoding. Named retail CPhysicsObj::SetPositionInternal(CTransition const*) (0x00515330) copies only the transition's current contact plane/water flag, walkability, sliding normal/valid flag, and collision state (0x005153E5–0x005154FE). It does not publish last_known_contact_plane or the SpherePath walkable polygon on this path, so those ordinary-update-only fields are intentionally absent from the immutable SetPosition result and remain unchanged. A zero expected velocity version in host preparation preserves the nonzero version captured when the operation was accepted; an intervening Vector/Movement therefore suppresses only the stale collision-velocity response. A bodyless cancellation terminates without fabricating a PhysicsBody or a host Withdraw projection. The two time domains remain explicit: PhysicsBody.LastUpdateTime consumes the instance simulation clock, while IRuntimeRemotePlacement.LastServerPositionTime remains Unix-UTC receipt time because the remote stale-velocity owner ages it against RuntimePhysicsState.UtcNowSeconds. A deferred wake therefore cannot make fresh authoritative remote velocity appear years old. Runtime preparation also applies the existing retail PositionFrameValidation before Core or prepared-mover caching, and caps synchronous Scatter/RandomScatter work at 64 attempts; this keeps valid authored retail request shapes while rejecting a hostile uint.MaxValue loop at the authority boundary.

One authority boundary intentionally remains open for 4B2:

  • RuntimePortalPlacementAuthority validates immutable token shape only; 4B2 must bind it to active RuntimeWorldTransitState generation, teleport sequence, destination, and host acknowledgement before reveal.

The former collision-report boundary is closed by RuntimeCollisionReportingState. Runtime now owns retail's exact-key object contact table, environment latch, strict ordinary/ethereal expiry, force-end, static and ReportAsEnvironment routing, reciprocal callback eligibility, missile-state clearing, ordered reentrant dispatch, and the report-result boolean which distinguishes placement Collided from NoValidPosition. Successful SetPosition commits reporting after Contact/OnWalkable and ground callbacks but before its single physical response and shadow reflood. See docs/research/2026-07-31-runtime-set-position-collision-reporting.md.

Slice 4B2 checkpoint 1 — public dormant host seam

The first 4B2 checkpoint exposes the dormant receipt owner through RuntimePlacementProjectionChannel. Graphical and no-window hosts can observe the one ordered placement stream, retry the exact immutable pending receipts, peek the FIFO head, measure pending debt, and acknowledge only the exact head. Mutation and retry calls require the current RuntimeGenerationToken; a stale generation, stale revision, reordered token, duplicate acknowledgement, or reused GUID cannot consume current placement debt. The channel delegates to RuntimeSetPositionState and RuntimeEntityObjectEventStream; it owns no second queue, mirror, or rollback path.

Shared local-controller body adoption is deliberately deferred. A reviewed prototype that prepared directly on the canonical body was rejected: a snapshot/rollback lease cannot safely coexist with reentrant SetPosition, remote/projectile binding, deletion/GUID reuse, owner replacement, object-clock epoch changes, or disposal. Correct adoption requires either an exclusive Runtime transaction integrated with every canonical writer, or off-canonical preparation followed by one validated atomic body/controller publication. Either choice belongs to the all-route ownership cutover, not this narrow dormant-seam checkpoint.

This remains a deliberately non-activating checkpoint. Production spawn, Position, projectile, drop/pickup/parent, and portal routes do not submit to the dormant SetPosition owner yet. The cutover remains blocked on exact ordered Setup spheres/scale/step heights/flags/cell-local preparation, presentation-only rebucketing, and placement-prefix quiescence before collision retirement. AP-1 and AD-1 remain open until those prerequisites and every production route land together.

AD-2 remains the explicit async adaptation: collision readiness can publish in a different frame from retail's blocking load. A failed wake is safely re- indexed to the next exact generation instead of inheriting retail's synchronous assumption. When older unbound survivors meet newer entities already indexed into that future generation, Runtime merges them into one bucket with the older survivor order first and retains one bucket-order entry. AP-1 and AD-1 remain open until 4B2 removes the legacy graphical/headless placement paths.

RuntimeSetPositionStateTests pins accepted-before-preparation ownership, portal-shape rejection, canonical-before-projection ordering, retry and reentrant discard, cross-landblock adjusted-cell park/wake, same-body identity, retained contact/water/sliding/velocity, exact generation gating, authored two-sphere retention, cold preparation, bounded priority-deadline rearm/cancel, zero-allocation empty ticks, independent ordered direct-child deadlines, actual collision-admission supersession/invalidation, missing exact indoor-cell generation rebind/wake, collision demotion/withdrawal preflight, failed-wake retry, malformed-preparation retry without cache poisoning, simulation-clock-domain wake, velocity-version preservation, derived body-bit writeback, immediate remote-velocity survival across the simulation/UTC clock boundary, invalid cell/frame/quaternion and extreme-scatter rejection before Core/caching, bodyless cancellation, newer Position/pickup/parent/delete, GUID reuse, reset, and complete index/node terminal convergence. Existing zero- allocation collision-generation gates remain unchanged on the no-deferred fast path.

The warmed immediate commit/ack route currently measures exactly 1,880 managed bytes per operation in the Release Runtime test host (1,000 iterations after 64 warmups); the regression gate caps it at 2,048 bytes. This dormant-path result is an explicit 4B2 activation blocker rather than a claim of allocation-free production readiness: 4B2 must either pool/remove the operation and projection envelopes or record an approved measured budget before routing frame-frequency placement through this owner.