Blitz3D+ Command Reference

FreePhysicsPlayer player

Parameters

player - live player handle.

Description

Frees a physics replay player and everything it owns.

Destroys the replay world, native player, copied file, registry/cooked resources, kept snapshots and debug geometry. It invalidates the handle. Other players and explicit live worlds remain independent. Runtime shutdown also frees outstanding players. A stale or wrong-kind handle is an error.

Player handles are separate from Physics world/body/shape/joint/query handles. Except PhysicsPlayerValid and CountPhysicsPlayers, commands require a live player and reject stale or wrong-kind handles. The player owns an isolated native world and debug geometry; it never returns native IDs or binds recorded bodies to arbitrary live entities. Replay restores recorded native physics, not Blitz input, scripts, assets, entity state or wrapper-only metadata.

Admission limits: file up to 64 MiB; selected frame limit up to 1000000; at most 2000000 operations, 4096 queries and 65536 recorded query hits/planes per frame. All players share a 128 MiB retained-file limit and a separate 128 MiB sum of configured keyframe budgets.

Cooked registry inspection checks versions, internal byte counts, baked hashes where present, array extents, geometry topology and reference kinds. Its cumulative work allowance is 256 MiB, counting nested compound references again. Meshes allow at most 1048576 vertices and triangles; compounds allow at most 65536 children and materials; inspected tree heights are limited to 64. Hull topology uses the native 256-entry limits.

Snapshot inspection runs before loading or restoring world state. It checks complete byte consumption, nested counts, free-ID uniqueness, ownership lists, solver/island back-references, graph colours, sensor links, broad-phase proxies/pairs, materials and primitive geometry. The graph pass uses at most 32 MiB of temporary storage outside the native allocation counter and at most 8388608 pair-table probes.

Saved joint values, contact materials, cached transforms and active manifold points are checked for finite values and required normalized rotations/normals. Collision caches must match the actual shape or compound child: simplex vertices, hull faces/paired edges and mesh/height-field triangles must be in range. Triangle caches allow at most 256 sorted, unique entries. Valid warm-start values are preserved; transient solver indices are rebuilt by Box3D.

Keyframe candidates are measured without allocating an image or copying cooked geometry. Candidates larger than the selected kept-keyframe budget are skipped; fitting images use an exact allocation and must pass snapshot restoration checks before being cached.

The conservative snapshot-allocation estimate must fit 256 MiB, including serialized arrays, owned materials, hull/compound references and native manifold-pool amplification. It excludes existing world storage, registry/input copies, temporary buffers and allocations during later simulation. These separate admission policies do not constitute a total native-memory cap.

Decoded operation values check finite primitive geometry, normalized rotations, ordered query bounds, body types and selected material, body and joint numeric preconditions before dispatch. Collider creation/replacement requires positive radius; zero-radius query proxies/movers remain allowed. Capsule creation still accepts coincident endpoints with positive radius. Native finite-value clamping/reordering is preserved where applicable.

Recorded time steps must also produce a positive finite substep duration and finite native reciprocals; extremely small positive values can be rejected before playback.

During playback, input IDs must still exist with matching generations and joint types. Joint bodies, cooked geometry kinds, compound restrictions and material indices are checked against the current replay world. Step or Seek can report a malformed-stream error after loading succeeds. After such an error, free the player and load a valid recording; its handle remains valid for cleanup. Recorded query-result mismatches report divergence and allow continued playback.

The recording must match the supported native v2 format (minor at most 2), pointer width, little-endian encoding, position precision and snapshot structure-layout hash. Native snapshot files are build-dependent; keep PhysicsBuildRevision with archived recordings. A matching structure hash does not guarantee identical physics across local solver patches. Admission checks are not an authentication or general-purpose hostile-file sandbox.

Requires Extended mode.

See also: LoadPhysicsPlayer, StepPhysicsPlayer, SeekPhysicsPlayer, PhysicsPlayerKeyframes, PhysicsPlayerDebugDraw, PhysicsDebugDraw.

Example

; FreePhysicsPlayer Example
; -------------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

; Recording writes a file, so ask first
Text 0,0,"This example records demo_replay.b3r next to itself, then deletes it."
Text 0,20,"Press Y to continue, any other key to exit."
Flip
WaitKey
If Not KeyDown(21) Then End

; Record four seconds of falling crates in a world that is never drawn
file$="demo_replay.b3r"
world=CreatePhysicsWorld()
scene=CreatePivot()
ground=CreateCube(scene)
PositionEntity ground,0,-0.5,0
ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
ground_shape=PhysicsBodyBox(ground_body,12,1,12)
For i=1 To 8
    crate=CreateCube(scene)
    PositionEntity crate,Rnd(-1,1),2+i*1.2,Rnd(-1,1)
    crate_body=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
    crate_shape=PhysicsBodyBox(crate_body,1,1,1)
Next
StartPhysicsRecording world
For frame=1 To 240
    StepPhysics world,1.0/60.0,4
Next
If Not StopPhysicsRecording(world,file) Then RuntimeError "Could not save the recording"
FreePhysicsWorld world
FreeEntity scene

; Load the recording, keeping the file so it can be loaded again
player=LoadPhysicsPlayer(file)

camera=CreateCamera()
PositionEntity camera,0,5,-12
RotateEntity camera,20,0,0

While Not KeyDown(1)

    ; Space pauses, R restarts; only a live player can play
    If KeyHit(57) Then paused=Not paused
    If PhysicsPlayerValid(player)
        If KeyHit(19) Then RestartPhysicsPlayer player
        If Not paused Then StepPhysicsPlayer player
    EndIf

    ; L frees the player, or loads the recording again
    If KeyHit(38)
        If PhysicsPlayerValid(player)
            FreePhysicsPlayer player
        Else
            player=LoadPhysicsPlayer(file)
        EndIf
    EndIf

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    If PhysicsPlayerValid(player) Then PhysicsPlayerDebugDraw player,camera

    Text 0,0,"Arrow keys: move camera   Space: pause   R: restart   L: free / load"
    Text 0,20,"Esc: exit"
    Text 0,40,"Player loaded: "+PhysicsPlayerValid(player)
    Text 0,60,"FreePhysicsPlayer frees the player and everything it owns"

    Flip

Wend

If PhysicsPlayerValid(player) Then FreePhysicsPlayer player
DeleteFile file
End

Index