b3dSetReflectionDistance

Sets reflection camera distance below surface (negative Y in local space, clamped 1.0-1000.0). Takes entity (reflective entity handle), distance (units below surface, clamped 1.0-1000.0). Returns nothing. Validates entity is reflective with reflection camera, clamps distance to 1.0-1000.0 range, stores in entity.reflectionDistance, repositions reflection camera to (0, -distance, 0) in local space (below reflective surface looking up). Controls how far below surface the reflection camera is positioned.

This function adjusts reflection camera viewing position relative to reflective surface. Camera placement: reflection camera positioned below surface (negative Y in entity's local coordinate system) looking upward (+90 degree pitch). Distance affects perspective and coverage. distance parameter: vertical distance in world units from surface (Y=0) to camera position, clamped 1.0-1000.0. Larger distance = wider viewing angle coverage, further objects visible in reflection, shallower perspective. Smaller distance = narrower coverage, closer objects only, steeper perspective. Default: b3dCreateReflectiveGrid calculates distance based on surface size (max(sizeX,sizeZ)/2 * 1.2, minimum 5.0), ensures full surface visible in reflection. Use cases: (1) Adjust reflection coverage (increase distance to capture more distant objects), (2) Perspective control (shallow vs steep reflection angles), (3) Performance tuning (smaller distance = less scene rendered), (4) Artistic effects (extreme distances for surreal reflections). Common pattern: water=b3dCreateReflectiveGrid(...), b3dSetReflectionDistance(water, 10.0), sets camera 10 units below water surface. Camera position: local coordinates (0, -distance, 0), negative Y because camera below surface, parented to grid so moves/rotates with it. FOV interaction: distance and FOV together determine visible area, larger distance with smaller FOV = narrow deep view, smaller distance with larger FOV = wide shallow view. Clamping: minimum 1.0 (prevents camera too close/inside surface), maximum 1000.0 (reasonable limit for large scenes). Calculation example: 20x20 unit grid, default distance = max(20,20)/2 * 1.2 = 12.0 units. Storage: stored in entity.reflectionDistance field for reference. Related: b3dSetReflectionFOV controls camera field of view (horizontal/vertical angle), together with distance determines reflection coverage, b3dCreateReflectiveGrid sets initial distance automatically, b3dCameraFOV adjusts FOV separately.