b3dEntityOrder

Sets entity render order (controls draw order for transparency/layering). Takes entity (entity handle), order (render order value, higher values drawn later). Returns nothing. Validates entity exists, sets entity.renderOrder=order. Controls rendering sequence for transparency sorting and layering effects.

This function controls draw order. Render order: determines sequence entities rendered within frame, entities sorted by renderOrder before drawing (lower values drawn first, higher values drawn later, on top of lower). Default order: entities have renderOrder=0 by default (normal rendering, order undefined among same-order entities). Order values: any integer allowed (negative, zero, positive), typical range -100 to +100 but no hard limits, relative values matter (order=1 drawn after order=0). Use cases: (1) Transparency sorting (transparent objects drawn back-to-front or front-to-back), (2) UI layering (HUD elements drawn on top with high order), (3) Decals/overlays (draw after base geometry to avoid z-fighting), (4) Sky/background (draw first with low/negative order), (5) Custom render passes (group entities by rendering technique). Common pattern: b3dEntityOrder(skybox, -100) draws background first, b3dEntityOrder(transparentObj, 50) draws transparent objects later, b3dEntityOrder(hudElement, 100) draws UI on top. Transparency handling: transparent objects typically need specific order (back-to-front for alpha blending requires sorting by distance, front-to-back for additive blending), renderOrder provides manual control (automatic distance sorting not implemented, use order for coarse layering). Z-fighting prevention: rendering coplanar surfaces in specific order reduces z-fighting (decals drawn after walls, shadows before objects), order doesn't replace depth testing (depth buffer still used, order controls submission sequence). Rendering loop: entities collected and sorted by renderOrder, entities with same order rendered in undefined sequence (may depend on insertion order, not guaranteed stable), sorting is stable (entities with same order maintain relative order from collection). Performance: setting order is O(1) (simple assignment), sorting during render is O(N log N) where N=entity count (performed once per frame), many unique order values may affect sorting performance (use few distinct values for best performance). Typical usage: set order once during scene setup, or dynamically adjust for effects (temporarily boost order for highlighted objects, lower order for fading objects). Order vs visibility: renderOrder doesn't affect visibility (visible flag controls rendering, order only controls sequence of visible entities). Related: entity.renderOrder field stores value, rendering system sorts by order, b3dHideEntity/ShowEntity control visibility, depth testing for z-ordering.