b3dPositionBaseTexture

Offsets base texture UV (offsetU/V, requires BBR_TEXTURE_UV flag, auto-clones shared materials). Takes entityHandle (mesh entity handle), offsetU (horizontal UV offset double), offsetV (vertical UV offset double). Returns nothing. Updates material.baseTextureOffset to {offsetU, offsetV}, controls base texture position/shift. Requires mesh.allowsUVTransforms = true (set via BBR_TEXTURE_UV flag in b3dCreateMesh or b3dLoadMesh). Mesh entities only.

This function offsets base texture coordinates. UV offsetting: offsetU/V add to texture coordinates (offsetU=0.5 shifts texture half-width right, offsetV=-0.5 shifts half-height down, wraps at boundaries with REPEAT mode). UV transform requirement: mesh must be created with BBR_TEXTURE_UV flag (b3dCreateMesh(slots, BBR_TEXTURE_UV, unique) or b3dLoadMesh(filename, slots, BBR_TEXTURE_UV, unique) enables UV transforms), prints helpful error if mesh.allowsUVTransforms = false. Material handling: surface-based meshes (procedural shapes) update all surface materials directly (all surfaces get same offset), loaded meshes (GLB models) auto-clone material if shared (calls EnsureUniqueMaterial to prevent affecting other entities). Use cases: (1) Texture alignment (offsetU=0.25 to align features with mesh geometry), (2) Scrolling textures (animate offsetU for horizontal scrolling, offsetV for vertical), (3) Pattern variation (different offset per instance for randomized appearance), (4) Multi-frame animation (offset to select different texture atlas frames), (5) Repositioning (adjust offset to center texture feature on mesh). Common patterns: center texture b3dPositionBaseTexture(entity, 0.5, 0.5), scroll horizontally offsetU = offsetU + 0.01 then b3dPositionBaseTexture(entity, offsetU, 0.0), random offset b3dPositionBaseTexture(entity, mathRnd(1.0), mathRnd(1.0)). Typical usage: offset to reposition base texture on mesh, animate offset for scrolling effects (conveyor belts, water flow), set random offset per instance for pattern variation, adjust offset to align texture features with mesh features. UV coordinate math: finalUV = baseUV + offset (offsetU=0.5 converts UV 0.0-1.0 to 0.5-1.5, texture wraps at 1.0 back to 0.0 with REPEAT mode). Offset wrapping: offsets > 1.0 or < 0.0 wrap around with REPEAT sampler (offsetU=1.5 same as offsetU=0.5 after wrapping, creates seamless tiling). Offset defaults: likely 0.0 if never set (verify during testing, 0.0 = no offset, texture aligned to UV origin). Material auto-cloning: loaded meshes (GLB) automatically call EnsureUniqueMaterial if shared (clones mesh and material for per-entity offset), prevents affecting other instances. Scrolling animation: animate offsetU or offsetV per frame for moving textures (water flow, conveyor motion, scrolling clouds). Performance: O(1) for loaded mesh (updates single material after clone), O(N) for surface-based mesh with N surfaces, offset applied in vertex/pixel shader. Validation: prints error if invalid entity handle, entity not mesh, UV transforms not allowed, entity has no valid material. Related: b3dScaleBaseTexture scales base texture UV, b3dRotateBaseTexture rotates base texture UV, b3dCreateMesh creates mesh with BBR_TEXTURE_UV flag, b3dLoadMesh loads mesh with BBR_TEXTURE_UV flag, b3dPositionDetailTexture offsets detail texture UV (separate from base).