b3dPositionEntity

Sets entity position in world space (modifies transform, routes to physics if body attached). Takes entity (entity handle), x (world X coordinate), y (world Y coordinate - positive up), z (world Z coordinate). Returns nothing. Validates entity exists, if physicsBodyHandle!=0 routes to b3dSetPhysicsBodyPosition for physics-driven positioning, otherwise sets entity.position with Y-axis negation (user +Y=up, internal -Y=up), marks worldMatrixDirty=true to trigger matrix recalculation. Modifies entity transform (doesn't change geometry).

This function sets entity world position. Transform vs geometry: PositionEntity modifies entity's transform matrix (affects rendering position), doesn't change mesh vertices (geometry unchanged), entity visually moves but mesh data identical. Contrast with b3dPositionMesh which modifies vertices directly (permanent geometry change). Y-axis negation: user coordinate system has +Y=up (standard for most 3D engines), internal DirectX system has -Y=up (DirectX convention), function negates Y on input: entity.position = XMFLOAT3(x, -y, z), ensures user's upward positions stored as downward internally. Query functions (GetEntityY) negate back on output. Physics integration: checks entity.physicsBodyHandle!=0 (non-zero means physics body attached), if physics body present, routes to b3dSetPhysicsBodyPosition instead of setting position directly, physics system owns transform (position updates propagate to entity during physics step), manual position setting via physics prevents desynchronization. If no physics body, standard positioning applies. WorldMatrix dirty flag: setting position marks worldMatrixDirty=true, triggers UpdateEntityWorldMatrix() during next render pass, recalculates matrix: WorldMatrix = Scale * Rotation * Translation, parent matrices multiply with child matrices (hierarchy propagation). Use cases: (1) Move objects in game loop (player, enemies, projectiles), (2) Place objects in scene setup (level loading, procedural placement), (3) Animate entity motion (scripted movement, cutscenes), (4) Teleportation (instant position change), (5) Snap to grid (quantized positioning). Common pattern: b3dPositionEntity(entity, x, y, z) every frame for movement, or b3dTranslateEntity for relative movement. Coordinate system: right-handed coordinate system (X=right, Y=up, Z=forward in user space), world space coordinates (not local/parent-relative). For parent-relative positioning use b3dSetEntityLocalPosition or compute manually. Parent-child relationships: positioned entity retains children (children move with parent), changing parent position affects children's world positions but not their local positions. Hierarchy: parent worldMatrixDirty propagates to all children (entire hierarchy recalculated). Performance: position setting is O(1) operation (no immediate recalculation), matrix recalculation deferred until render (lazy evaluation), setting multiple properties (position, rotation, scale) before render efficient (single matrix update). Physics performance: routing to physics system triggers physics body update (more expensive than non-physics positioning), physics updates handled by Jolt Physics (external solver). Typical usage: position entities at creation, update positions in game loop for dynamic objects, route through physics for physically-simulated objects. Validation: invalid entity handles silently ignored (no error). Related: b3dPositionMesh modifies mesh vertices directly (permanent geometry change), b3dTranslateEntity for relative movement, b3dSetPhysicsBodyPosition for physics body positioning, b3dGetEntityPosition for querying position, UpdateEntityWorldMatrix recalculates world matrix.