src/three

src/three/ — the three.js RENDERER BINDING (RFC 0001 signals+bindings).

In the koota-native signals+bindings model, the core is renderer-free and koota traits ARE the signals; this module is the 3D binding that subscribes to the placement signals and reconciles a three scene. It is reachable ONLY via the declarative-hex-worlds/three subpath, and three / @react-three/fiber are OPTIONAL peer dependencies — a consumer installs them only if they import this binding (the renderer-optionality contract enforces the core never pulls them in). src/canvas2d is the sibling 2D binding subscribing to the same signals.

disposeGameboardThreeResources(ctx) gives consumers a guided cleanup path for geometry/material allocations.

Interfaces

AccessoryAttachmentResult

Defined in: packages/declarative-hex-worlds/src/three/accessories.ts:17

Result of attaching an accessory — the node it parented to, or a miss.

Properties

attached

readonly attached: boolean

Defined in: packages/declarative-hex-worlds/src/three/accessories.ts:20

True if the target node was found and the accessory parented to it.

id

readonly id: string

Defined in: packages/declarative-hex-worlds/src/three/accessories.ts:18

node?

readonly optional node?: Object3D<Object3DEventMap>

Defined in: packages/declarative-hex-worlds/src/three/accessories.ts:22

The node the accessory attached to (undefined on a miss).

GameboardGltfLike

Defined in: packages/declarative-hex-worlds/src/three/three.ts:57

Minimal GLTF loader result shape used by the renderer helpers.

Properties

animations?

optional animations?: readonly AnimationClip[]

Defined in: packages/declarative-hex-worlds/src/three/three.ts:61

Animation clips embedded in the GLTF.

scene

scene: Object3D

Defined in: packages/declarative-hex-worlds/src/three/three.ts:59

Root Three.js scene/object loaded from GLTF.

GameboardGltfLoader

Defined in: packages/declarative-hex-worlds/src/three/three.ts:67

Minimal async loader contract compatible with GLTFLoader.

Methods

loadAsync()

loadAsync(url): Promise<GameboardGltfLike>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:69

Loads a GLTF/GLB URL and returns the scene plus optional clips.

Parameters

url

string

Returns

Promise<GameboardGltfLike>

GameboardObjectUserData

Defined in: packages/declarative-hex-worlds/src/three/three.ts:257

User-data payload attached to rendered objects for picking and interaction.

Properties

actorId?

optional actorId?: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:271

Actor id when the placement represents a runtime actor.

actorKind?

optional actorKind?: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:273

Actor kind when supplied by placement metadata.

assetId

assetId: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:263

Source asset id.

kind

kind: GameboardPlacementKind

Defined in: packages/declarative-hex-worlds/src/three/three.ts:265

Placement kind from the gameboard plan.

layer

layer: GameboardPlacementLayer

Defined in: packages/declarative-hex-worlds/src/three/three.ts:267

Placement layer from the gameboard plan.

placementId

placementId: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:259

Placement id represented by this object.

requiresExtra

requiresExtra: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:269

Whether this object depends on local EXTRA or external assets.

sourcePack?

optional sourcePack?: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:275

Source pack label for external pieces.

tileKey

tileKey: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:261

Origin tile key.

GameboardPlacementObjectSyncError

Defined in: packages/declarative-hex-worlds/src/three/three.ts:299

Load/sync error for a specific placement.

Properties

error

error: unknown

Defined in: packages/declarative-hex-worlds/src/three/three.ts:303

Original error value.

placement

placement: GameboardPlacementSpec

Defined in: packages/declarative-hex-worlds/src/three/three.ts:301

Placement that failed to load or sync.

GameboardPlacementObjectSyncOptions

Defined in: packages/declarative-hex-worlds/src/three/three.ts:281

Options for reconciling a Three.js scene with a placement list.

Extends

LoadGameboardPlacementObjectOptions

Properties

animationUrlResolver?

optional animationUrlResolver?: (placement) => string | undefined

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:47

App-specific animation URL resolver.

Parameters

placement

GameboardPlacementSpec

Returns

string | undefined

Inherited from

LoadGameboardPlacementObjectOptions.animationUrlResolver

animationUrls?

optional animationUrls?: Readonly<Record<string, string>>

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:45

Explicit asset-id-to-animation-URL map.

Inherited from

LoadGameboardPlacementObjectOptions.animationUrls

assetUrls?

optional assetUrls?: Readonly<Record<string, string>>

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:32

Explicit asset-id-to-URL overrides, useful for local-only Vite @fs assets.

Inherited from

LoadGameboardPlacementObjectOptions.assetUrls

baseUrl?

optional baseUrl?: string | URL

Defined in: packages/declarative-hex-worlds/src/manifest/schema.ts:147

Base URL applied to every model path when no edition-specific base exists.

Inherited from

LoadGameboardPlacementObjectOptions.baseUrl

bootstrapAssetRoot?

optional bootstrapAssetRoot?: string | URL

Defined in: packages/declarative-hex-worlds/src/manifest/schema.ts:160

Consumer's bootstrap asset root (per PRD RB3).

When set, manifest sourcePath values (e.g. buildings/blue/foo.gltf) are joined with this root to produce the resolved URL — <bootstrapAssetRoot>/<sourcePath> (flat layout, no subdirectory prefix).

Honored only when neither baseUrl nor a matching editionBaseUrls entry is set; explicit base URLs always win.

Inherited from

LoadGameboardPlacementObjectOptions.bootstrapAssetRoot

cacheLoads?

optional cacheLoads?: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:225

Deduplicates loader calls by URL so multiple placements sharing an asset trigger exactly one loadAsync invocation. The cached GLTF source is never mutated directly — each placement still receives its own cloned Object3D scene instance. Defaults to true.

Inherited from

LoadGameboardPlacementObjectOptions.cacheLoads

catalog?

optional catalog?: ManifestAssetCatalog

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:30

Manifest or manifest bundle used for packaged FREE/EXTRA asset ids.

Inherited from

LoadGameboardPlacementObjectOptions.catalog

clipName?

optional clipName?: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:216

Optional clip name override. Defaults to placement metadata when present.

Inherited from

LoadGameboardPlacementObjectOptions.clipName

clipNameResolver?

optional clipNameResolver?: (placement) => string | undefined

Defined in: packages/declarative-hex-worlds/src/three/three.ts:291

Per-placement clip-name resolver.

Parameters

placement

GameboardPlacementSpec

Returns

string | undefined

deltaSeconds?

optional deltaSeconds?: number

Defined in: packages/declarative-hex-worlds/src/three/three.ts:289

Optional animation delta to advance during this sync pass.

editionBaseUrls?

optional editionBaseUrls?: Partial<Record<"free" | "extra", string | URL>>

Defined in: packages/declarative-hex-worlds/src/manifest/schema.ts:149

Per-edition base URLs, useful when FREE is packaged and EXTRA is local.

Inherited from

LoadGameboardPlacementObjectOptions.editionBaseUrls

fallback?

optional fallback?: (placement) => string | undefined

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:34

Last-chance resolver for app-specific asset stores.

Parameters

placement

GameboardPlacementSpec

Returns

string | undefined

Inherited from

LoadGameboardPlacementObjectOptions.fallback

loader?

optional loader?: GameboardGltfLoader

Defined in: packages/declarative-hex-worlds/src/three/three.ts:206

GLTF-compatible async loader. OPTIONAL: only required when a placement actually resolves to a gltf request. A tileset-ONLY board (every placement resolves to a tileset-cell) needs no GLTF loader — supply only textureLoader. A gltf request with no loader throws a clear error at load time.

Inherited from

LoadGameboardPlacementObjectOptions.loader

parent?

optional parent?: Object3D<Object3DEventMap>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:283

Parent object to receive loaded placement objects.

playAnimation?

optional playAnimation?: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:218

Whether to start the selected animation immediately. Defaults to true.

Inherited from

LoadGameboardPlacementObjectOptions.playAnimation

records?

optional records?: Map<string, LoadedGameboardPlacementObject>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:285

Mutable cache keyed by placement id.

removeStale?

optional removeStale?: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:287

Remove cached objects that no longer appear in the placement list.

source?

optional source?: AssetSource

Defined in: packages/declarative-hex-worlds/src/three/three.ts:212

Optional asset source (RFC0-7). When provided, a placement resolving to a tileset-cell request is rendered as a textured-hex mesh instead of a GLTF; a gltf request (or no resolution) falls through to the GLTF loader path.

Inherited from

LoadGameboardPlacementObjectOptions.source

textureLoader?

optional textureLoader?: GameboardSheetTextureLoader

Defined in: packages/declarative-hex-worlds/src/three/three.ts:214

Sheet-texture loader, required when source can emit tileset-cell requests.

Inherited from

LoadGameboardPlacementObjectOptions.textureLoader

throwOnError?

optional throwOnError?: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:293

Rethrow load errors instead of collecting them in the result.

GameboardPlacementObjectSyncResult

Defined in: packages/declarative-hex-worlds/src/three/three.ts:309

Result of a placement-object sync pass.

Properties

errors

errors: readonly GameboardPlacementObjectSyncError[]

Defined in: packages/declarative-hex-worlds/src/three/three.ts:319

Non-fatal load errors collected during this pass.

loaded

loaded: readonly LoadedGameboardPlacementObject[]

Defined in: packages/declarative-hex-worlds/src/three/three.ts:313

Objects loaded during this pass.

records

records: Map<string, LoadedGameboardPlacementObject>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:311

Final mutable cache keyed by placement id.

removed

removed: readonly LoadedGameboardPlacementObject[]

Defined in: packages/declarative-hex-worlds/src/three/three.ts:317

Objects removed during this pass.

updated

updated: readonly LoadedGameboardPlacementObject[]

Defined in: packages/declarative-hex-worlds/src/three/three.ts:315

Existing objects updated in place during this pass.

GameboardSheetTextureLoader

Defined in: packages/declarative-hex-worlds/src/three/three.ts:169

Minimal async loader contract for tileset sheet textures. Compatible with a three TextureLoader wrapped to also report the sheet's pixel dimensions (needed for per-cell UV normalization in buildTexturedHexMesh).

Methods

loadAsync()

loadAsync(url): Promise<SheetTexture>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:171

Load a sheet image URL and return the texture plus its pixel dimensions.

Parameters

url

string

Returns

Promise<SheetTexture>

LoadedGameboardPlacementObject

Defined in: packages/declarative-hex-worlds/src/three/three.ts:231

Loaded Three.js object plus gameboard metadata and animation state.

Properties

activeClip?

optional activeClip?: AnimationClip

Defined in: packages/declarative-hex-worlds/src/three/three.ts:247

Selected active clip.

animationAction?

optional animationAction?: AnimationAction

Defined in: packages/declarative-hex-worlds/src/three/three.ts:251

Action created for the active clip.

animationUrl?

optional animationUrl?: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:241

Resolved animation URL, when separate from the model.

assetId

assetId: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:235

Asset id this object was loaded from.

clips

clips: readonly AnimationClip[]

Defined in: packages/declarative-hex-worlds/src/three/three.ts:245

Available animation clips from model and optional animation source.

mixer?

optional mixer?: AnimationMixer<AnimationMixerEventMap>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:249

Animation mixer bound to the loaded object.

modelUrl

modelUrl: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:239

Resolved model URL.

object

object: Object3D

Defined in: packages/declarative-hex-worlds/src/three/three.ts:237

Three.js object added to the scene.

placementId

placementId: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:233

Placement id this object represents.

transform

transform: AssetTransform

Defined in: packages/declarative-hex-worlds/src/three/three.ts:243

Last transform applied to the object.

LoadGameboardPlacementObjectOptions

Defined in: packages/declarative-hex-worlds/src/three/three.ts:197

Options for loading one placement object.

Extends

GameboardPlacementAssetUrlOptions.GameboardPlacementAnimationUrlOptions

Extended by

GameboardPlacementObjectSyncOptions

Properties

animationUrlResolver?

optional animationUrlResolver?: (placement) => string | undefined

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:47

App-specific animation URL resolver.

Parameters

placement

GameboardPlacementSpec

Returns

string | undefined

Inherited from

GameboardPlacementAnimationUrlOptions.animationUrlResolver

animationUrls?

optional animationUrls?: Readonly<Record<string, string>>

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:45

Explicit asset-id-to-animation-URL map.

Inherited from

GameboardPlacementAnimationUrlOptions.animationUrls

assetUrls?

optional assetUrls?: Readonly<Record<string, string>>

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:32

Explicit asset-id-to-URL overrides, useful for local-only Vite @fs assets.

Inherited from

GameboardPlacementAssetUrlOptions.assetUrls

baseUrl?

optional baseUrl?: string | URL

Defined in: packages/declarative-hex-worlds/src/manifest/schema.ts:147

Base URL applied to every model path when no edition-specific base exists.

Inherited from

GameboardPlacementAssetUrlOptions.baseUrl

bootstrapAssetRoot?

optional bootstrapAssetRoot?: string | URL

Defined in: packages/declarative-hex-worlds/src/manifest/schema.ts:160

Consumer's bootstrap asset root (per PRD RB3).

Honored only when neither baseUrl nor a matching editionBaseUrls entry is set; explicit base URLs always win.

Inherited from

GameboardPlacementAssetUrlOptions.bootstrapAssetRoot

cacheLoads?

optional cacheLoads?: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:225

catalog?

optional catalog?: ManifestAssetCatalog

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:30

Manifest or manifest bundle used for packaged FREE/EXTRA asset ids.

Inherited from

GameboardPlacementAssetUrlOptions.catalog

clipName?

optional clipName?: string

Defined in: packages/declarative-hex-worlds/src/three/three.ts:216

Optional clip name override. Defaults to placement metadata when present.

editionBaseUrls?

optional editionBaseUrls?: Partial<Record<"free" | "extra", string | URL>>

Defined in: packages/declarative-hex-worlds/src/manifest/schema.ts:149

Per-edition base URLs, useful when FREE is packaged and EXTRA is local.

Inherited from

GameboardPlacementAssetUrlOptions.editionBaseUrls

fallback?

optional fallback?: (placement) => string | undefined

Defined in: packages/declarative-hex-worlds/src/asset-source/placement-resolution.ts:34

Last-chance resolver for app-specific asset stores.

Parameters

placement

GameboardPlacementSpec

Returns

string | undefined

Inherited from

GameboardPlacementAssetUrlOptions.fallback

loader?

optional loader?: GameboardGltfLoader

Defined in: packages/declarative-hex-worlds/src/three/three.ts:206

playAnimation?

optional playAnimation?: boolean

Defined in: packages/declarative-hex-worlds/src/three/three.ts:218

Whether to start the selected animation immediately. Defaults to true.

source?

optional source?: AssetSource

Defined in: packages/declarative-hex-worlds/src/three/three.ts:212

textureLoader?

optional textureLoader?: GameboardSheetTextureLoader

Defined in: packages/declarative-hex-worlds/src/three/three.ts:214

Sheet-texture loader, required when source can emit tileset-cell requests.

SheetTexture

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:30

A texture whose full pixel dimensions are known (for UV normalization).

Properties

sheetHeight

sheetHeight: number

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:35

Full sheet height in pixels.

sheetWidth

sheetWidth: number

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:33

Full sheet width in pixels.

texture

texture: Texture

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:31

TextureBindingResult

Defined in: packages/declarative-hex-worlds/src/three/texture-binding.ts:24

Result of applying a texture binding — the count of materials updated.

Properties

assetId

readonly assetId: string

Defined in: packages/declarative-hex-worlds/src/three/texture-binding.ts:25

materialsUpdated

readonly materialsUpdated: number

Defined in: packages/declarative-hex-worlds/src/three/texture-binding.ts:26

TexturedHexMeshOptions

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:39

Options for building a textured hex mesh.

Properties

cell

cell: CellRect

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:41

doubleSide?

optional doubleSide?: boolean

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:59

Whether the mesh is double-sided (default: true, so top-down cameras see it).

hex

hex: HexDims

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:42

opacity?

optional opacity?: number

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:73

Optional opacity in [0, 1]. < 1 switches the material to the TRANSPARENT queue (a translucent shroud) while KEEPING alphaTest so the hex corners still cut out. Omitted or >= 1 leaves the default OPAQUE-queue cutout path (transparent: false) byte-for-byte unchanged, preserving seamless tessellation.

orientation?

optional orientation?: "pointy" | "flat"

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:57

Hex orientation (only meaningful for shape: 'hex'). 'pointy' (default) has a vertex at the top; 'flat' has a flat edge at the top.

shape?

optional shape?: "hex" | "quad"

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:52

Draw shape (see AssetRenderRequest['shape']):

'quad' (default): the full cell rect is a rectangle spanning hex.width × hex.height. Painterly hex atlases paint each cell as a flattened hex with TRANSPARENT corners; a full quad lets neighbours' opaque bodies fill each other's transparent corners, tessellating SEAMLESSLY. This matches the canvas-2D binding, which always blits the whole cell.
'hex': clip to a hexagon silhouette. Only for opaque edge-to-edge cells.

sheet

sheet: SheetTexture

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:40

tint?

optional tint?: object

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:66

Optional multiplicative RGB tint (channels [0, 1], white ⇒ identity), applied to the material color so a game can shade a shared atlas per placement (fog-of-war / season / team). Omitted ⇒ the material keeps its default white colour (no tint).

b

b: number

g

g: number

r

r: number

Functions

applyPlacementShading()

applyPlacementShading(object, tint, opacity): void

Defined in: packages/declarative-hex-worlds/src/three/three.ts:671

Apply optional per-placement shading (tint / opacity) to every material in a loaded GLTF model, mirroring the tileset-cell path so 3D units/props can be fog-shrouded / team-tinted the same way tiles are. Both are opt-in: when neither is set the materials are untouched (the model renders byte-identically). A tint multiplies each material's color; an opacity < 1 makes it translucent. The cloned model owns its materials (SkeletonUtils clone), so mutating them here does not leak into the shared cached scene's materials — except that three's GLTF loader may SHARE a material instance across meshes/clones, so we clone each material before mutating to keep the shading strictly per-placement.

Parameters

object

Object3D

tint

{ b: number; g: number; r: number; } | undefined

opacity

number | undefined

Returns

void

applyTextureBinding()

applyTextureBinding(modelRoot, binding, texture, normalTexture?): TextureBindingResult

Defined in: packages/declarative-hex-worlds/src/three/texture-binding.ts:43

Apply a texture binding to a loaded model. Traverses modelRoot, and for every mesh whose name is targeted by the binding (a binding with no targets matches all meshes), sets the base-color map (and normalMap when a normal texture is given) on its material(s). Returns how many materials were updated.

Parameters

modelRoot

Object3D

binding

TextureBinding

texture

Texture

normalTexture?

Texture<unknown, TextureEventMap>

Returns

TextureBindingResult

applyTransform()

applyTransform(object, transform): Object3D

Defined in: packages/declarative-hex-worlds/src/three/three.ts:654

Applies a gameboard transform to a Three.js object.

Parameters

object

Object3D

transform

AssetTransform

Returns

Object3D

attachAccessoryToModel()

attachAccessoryToModel(characterRoot, attachment, accessoryObject): AccessoryAttachmentResult

Defined in: packages/declarative-hex-worlds/src/three/accessories.ts:31

Attach accessoryObject to the attachment.node bone/node of characterRoot, applying the accessory's local transform. Returns whether the node was found. On a miss the accessory is left un-parented and attached is false — the caller decides whether a missing node is fatal (validate at author time via validateAccessoryAttachments).

Parameters

characterRoot

Object3D

attachment

AccessoryAttachment

accessoryObject

Object3D

Returns

AccessoryAttachmentResult

buildHexGeometry()

buildHexGeometry(cell, hex, sheetWidth, sheetHeight, orientation?): BufferGeometry

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:90

Build a hexagon BufferGeometry in the XZ plane (Y=0), with UVs mapping each corner + center to the given cell rect of a sheet. The hex spans hex.width on X and hex.height on Z.

Parameters

cell

CellRect

hex

HexDims

sheetWidth

number

sheetHeight

number

orientation?

"pointy" | "flat"

Returns

BufferGeometry

buildTexturedHexMesh()

buildTexturedHexMesh(options): Mesh

Defined in: packages/declarative-hex-worlds/src/three/textured-hex.ts:182

Build a textured Mesh for a tileset-cell render request. Defaults to a full quad (shape: 'quad') — the seamless path for transparent-corner painterly hex atlases; shape: 'hex' clips to a hexagon for opaque edge-to-edge cells. Sampled with a MeshBasicMaterial over the cell. The caller owns the returned mesh's lifecycle (position it on the board, add to the scene, dispose on removal).

Parameters

options

TexturedHexMeshOptions

Returns

Mesh

detachAccessory()

detachAccessory(accessoryObject): void

Defined in: packages/declarative-hex-worlds/src/three/accessories.ts:49

Detach a previously-attached accessory from its parent node.

Parameters

accessoryObject

Object3D

Returns

void

findGameboardPlacementObjectUserData()

findGameboardPlacementObjectUserData(object): GameboardObjectUserData | undefined

Defined in: packages/declarative-hex-worlds/src/three/three.ts:598

Walks up the parent chain to find gameboard user data for a picked object.

Parameters

object

Object3D

Returns

GameboardObjectUserData | undefined

findLoadedGameboardPlacementObjectForObject()

findLoadedGameboardPlacementObjectForObject(object, records): LoadedGameboardPlacementObject | undefined

Defined in: packages/declarative-hex-worlds/src/three/three.ts:615

Resolves a picked object back to the loaded placement record cache.

Parameters

object

Object3D

records

ReadonlyMap<string, LoadedGameboardPlacementObject>

Returns

LoadedGameboardPlacementObject | undefined

frameObjectPosition()

frameObjectPosition(asset, margin?): Vector3

Defined in: packages/declarative-hex-worlds/src/three/three.ts:732

Returns a camera-friendly offset for framing one manifest asset preview.

Parameters

asset

MedievalHexagonAsset

margin?

number = 1.7

Returns

Vector3

gameboardInteractionTargetForObject()

gameboardInteractionTargetForObject(object): GameboardInteractionTargetInput | undefined

Defined in: packages/declarative-hex-worlds/src/three/three.ts:627

Converts picked Three.js object metadata into an actor/placement/tile target for command and interaction helpers.

Parameters

object

Object3D

Returns

GameboardInteractionTargetInput | undefined

loadGameboardPlacementObject()

loadGameboardPlacementObject(placement, options): Promise<LoadedGameboardPlacementObject>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:362

Parameters

placeObjectOnHex()

placeObjectOnHex(object, coordinates, options?): Object3D

Defined in: packages/declarative-hex-worlds/src/three/three.ts:716

Places an object directly on a board hex without creating a placement record.

Parameters

object

Object3D

coordinates

HexCoordinates

options?

elevation?

number

positionOffset?

GameboardPlacementPositionOffset

rotationY?

number

scale?

number

Returns

Object3D

readGameboardPlacementObjectUserData()

readGameboardPlacementObjectUserData(object): GameboardObjectUserData | undefined

Defined in: packages/declarative-hex-worlds/src/three/three.ts:587

Reads gameboard user data directly attached to an object.

Parameters

object

Object3D

Returns

GameboardObjectUserData | undefined

syncGameboardPlacementObject()

syncGameboardPlacementObject(loaded, placement, options?): LoadedGameboardPlacementObject

Defined in: packages/declarative-hex-worlds/src/three/three.ts:550

Updates one loaded object to match the current placement transform and user data.

Parameters

loaded

LoadedGameboardPlacementObject

placement

GameboardPlacementSpec

options?

deltaSeconds?

number

Returns

LoadedGameboardPlacementObject

syncGameboardPlacementObjects()

syncGameboardPlacementObjects(placements, options): Promise<GameboardPlacementObjectSyncResult>

Defined in: packages/declarative-hex-worlds/src/three/three.ts:464

Reconciles a Three.js object cache with the current placement list.

Existing records are updated in place, changed asset URLs are reloaded, stale records are removed by default, and load failures are returned unless throwOnError is set.