b3dLoadBRSFile

Loads BRS scene file (BambooBasic Resource Scene format). Takes filename (path to .brs scene file as String, relative or absolute path). Returns scene handle as Int (positive integer on success, 0 or negative on failure, use with b3dGetBRSModellerObject and b3dGetBRSPropObject to extract scene contents).

BRS format: custom BambooBasic scene file format (stores 3D scene hierarchy, multiple objects/entities, props and modeller objects, metadata and properties), alternative to loading individual GLB/OBJ files (single file contains entire scene, organized hierarchy, named objects for easy access). Scene handle: opaque handle referencing loaded BRS data (not an entity handle, use extraction functions to get actual entities).

BRS contents: modeller object (primary scene object, main 3D model or scene root, accessed with b3dGetBRSModellerObject), prop objects (named additional objects in scene, decorations, interactive elements, lights, cameras, accessed with b3dGetBRSPropObject(sceneHandle, "propName")). Workflow: load BRS file (scene = b3dLoadBRSFile("level.brs")), extract modeller object (main = b3dGetBRSModellerObject(scene) to get main entity), extract props (door = b3dGetBRSPropObject(scene, "door1") to get named prop entity), use entities normally (position, render, physics, etc).

Use cases: (1) Level loading (entire level in single BRS file with all objects), (2) Prefab scenes (reusable scene templates with named objects), (3) Organized assets (complex scenes with multiple named objects), (4) Tool pipeline (export from 3D editor to BRS for easy BambooBasic loading). Common patterns: load level (scene = b3dLoadBRSFile("level1.brs"), extract objects, position and configure), load prefab (scene = b3dLoadBRSFile("house.brs"), get door = b3dGetBRSPropObject(scene, "door"), attach interaction logic).

File format: BRS is BambooBasic-specific (not standard 3D format like GLB/OBJ, created by BambooBasic tools or custom exporter, contains BambooBasic-specific metadata), may include (mesh data, textures, materials, object names, hierarchies, custom properties). Performance: single file load efficient (one I/O operation loads entire scene, faster than loading many individual files), parsed once (entities extracted from loaded data as needed).

Validation: returns 0 or negative if file not found or invalid format, returns positive scene handle if successful (handle valid until scene unloaded, extract entities immediately or store handle for later extraction). Error handling: check return value (if scene <= 0 then error, file missing or corrupted), provide fallback (load default scene or display error message).

Related: b3dGetBRSModellerObject extracts main modeller object from scene, b3dGetBRSPropObject extracts named prop object from scene, b3dLoadMesh loads individual mesh file (alternative to BRS for single objects).