b3dEntityY

Returns entity Y position with coordinate system negation (user +Y=up, 0.0 if invalid). Takes entity (entity handle). Returns Y coordinate as Double (-entity.position.y, negated for user coordinate system, 0.0 if entity doesn't exist). Validates entity exists, returns -position.y (negates internal coordinate to user coordinate), returns 0.0 if invalid handle. Query function for entity vertical position.

This function retrieves entity Y coordinate with axis negation. Y-axis negation: internal coordinate system has -Y=up (DirectX convention), user coordinate system has +Y=up (Blitz3D/standard convention), function negates: returns -entity.position.y, converts internal to user coordinates. Return value: positive values mean entity is above origin (user's "up"), negative values mean entity is below origin (user's "down"), 0.0 if entity handle invalid. Coordinate system consistency: all position setters negate Y on input (b3dPositionEntity negates user Y to internal -Y), all position getters negate Y on output (b3dEntityY negates internal -Y back to user Y), maintains consistent user coordinate system throughout API. Use cases: (1) Height queries (check entity altitude for jumping, flying, terrain following), (2) Gravity logic (apply downward force based on Y position), (3) Vertical boundaries (check if entity above/below limits), (4) Debugging (log vertical position), (5) UI display (show height to user). Common pattern: y = b3dEntityY(entity), if y < groundLevel: apply gravity, or height = b3dEntityY(player) - b3dEntityY(ground). Typical usage: query Y separately for vertical logic (gravity, jumping, altitude), combine with X/Z for full 3D position. Position synchronization: if entity has physics body, position synced from physics (entity.position updated from physics body), returned value reflects physics-driven position (negated to user coordinates). Parent relationships: if entity parented, position is local coordinates (relative to parent), returned value is local Y negated (not world Y). Invalid handle: returns 0.0 for non-existent entities (silent fail), 0.0 could be valid Y position (ground level), check entity validity separately. Performance: O(1) lookup (hash map find, field access with negation, very fast). Related: b3dEntityX returns X position (no negation), b3dEntityZ returns Z position (no negation), b3dPositionEntity sets position (negates Y on input), b3dMoveEntity moves entity.