b3dGetBRSPropObject

Extracts named prop object entity from loaded BRS scene. Takes sceneHandle (scene handle from b3dLoadBRSFile, valid loaded BRS scene), propName (name of prop object as String, case-sensitive name assigned in BRS file). Returns entity handle of named prop object as Int (standard entity handle usable with all entity functions, 0 or negative if prop not found).

Prop objects: named objects in BRS scene beyond main modeller object (doors, windows, lights, cameras, decorations, interactive elements, any named sub-object in scene), multiple props per BRS scene (each with unique name, accessed individually by name). Returned entity: standard BambooBasic entity handle (use with all entity functions, manipulate like any loaded mesh).

Prop naming: names assigned in BRS creation tool (3D editor or BRS exporter, typically descriptive names like "door1", "window_main", "light_overhead"), case-sensitive (must match exact name in BRS file, "Door1" != "door1"). Multiple props: extract multiple props from same scene (call b3dGetBRSPropObject multiple times with different names, each returns separate entity handle).

Workflow: load BRS (scene = b3dLoadBRSFile("building.brs")), extract props (door = b3dGetBRSPropObject(scene, "frontDoor"), window = b3dGetBRSPropObject(scene, "window1")), use entities (b3dPositionEntity(door, ...), attach interaction logic to door). Use cases: (1) Extract interactive objects (doors, buttons, levers by name), (2) Get named lights/cameras (configure lighting or camera positions from scene), (3) Access decorative elements (specific furniture or props), (4) Organized level loading (named spawn points, trigger zones).

Prop not found: returns 0 or negative if propName doesn't exist in scene (typo in name, prop not in BRS file, name case mismatch), check return value before use (if prop <= 0 then warning or error). Common mistakes: name typo (check exact spelling in BRS file), case mismatch (use exact case from BRS), prop in different BRS file (verify correct scene loaded).

Validation: returns 0 or negative if sceneHandle invalid or propName not found, returns entity handle if successful (valid entity, can be used immediately). Error handling: check return value (if door <= 0 then Print "Door not found in scene"), provide fallback (use default object or skip interaction).

Related: b3dLoadBRSFile loads BRS scene (call before this function), b3dGetBRSModellerObject extracts main modeller object (separate from prop objects, use both for complete scene).