|
instance - prefab placement entity part$ - local part ID instance_path$ (optional) - JSON array of nested placement IDs; "[]" (default) component$ (optional) - stable component ID to select; "" (default) |
|
Finds a named part inside a prefab instance. Returns the matching entity, or 0 if absent - use it to find the door of a spawned house or the turret of a tank. Lookup survives label changes, array reordering and reparenting. A listener component selects its actual listener entity; other supported components share their part's native entity. Malformed selectors are runtime errors. Returned parts remain owned by their instance. For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow. See also: PrefabPartID, GetOwnedEntity, EntityOwner, PrefabSourceID. |
; CreatePrefabDocument Example
; ----------------------------
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
; Author a small lamp post in a world document: a root with a post and a lamp
document=CreateWorldDocument("prefab-example","Lamp post")
text$="{'protocol':'blitz3d.world-document-edit','version':1,'expectedRevision':0,'operations':["
text=text+"{'op':'entity.add','entity':{'id':'root','components':[]}},"
text=text+"{'op':'entity.add','entity':{'id':'post','parent':'root','components':[{'id':'mesh','type':'model','primitive':'cylinder'}]}},"
text=text+"{'op':'entity.add','entity':{'id':'lamp','parent':'root','transform':{'position':[0,1.5,0]},'components':[{'id':'bulb','type':'model','primitive':'sphere'}]}}]}"
edit=ParseJson(Replace(text,"'",Chr(34)))
If ApplyWorldDocumentEdit(document,edit)=0 Then RuntimeError WorldDocumentError()
FreeJson edit
; Turn the root and its descendants into a reusable prefab (kept in memory)
prefab=CreatePrefabDocument(document,"root")
If prefab=0 Then RuntimeError ResourceDocumentError()
FreeWorldDocument document
; Instantiate it through an async world, then place two copies
world=LoadResourceDocumentAsync(prefab)
If world=0 Then RuntimeError ResourceDocumentError()
FreeResourceDocument prefab
While WorldReady(world)=0
If WorldLoadState(world)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(world)
UpdateAsyncLoads 2
Wend
SetWorld world
original=FindWorldEntity(world,"instance")
copy=CopyEntity(original)
PositionEntity original,-2,0,0
PositionEntity copy,2,0,0
camera=CreateCamera()
PositionEntity camera,0,1,-8
light=CreateLight()
RotateEntity light,35,-25,0
; Find parts by their stable IDs; the copy's bulb gets its own colour
EntityColor FindPrefabPart(copy,"lamp","[]","bulb"),255,220,90
lamp=FindPrefabPart(original,"lamp")
; A part stays owned by its instance even when reparented elsewhere
EntityParent lamp,0,True
released=False
While Not KeyDown(1)
; Space frees the left instance - its detached lamp goes with it
If KeyHit(57) And original<>0
FreeEntity original
original=0
released=True
EndIf
TurnEntity copy,0,0.5,0
; Arrow keys move the camera
If KeyDown(200) Then MoveEntity camera,0,0,0.1
If KeyDown(208) Then MoveEntity camera,0,0,-0.1
If KeyDown(203) Then TurnEntity camera,0,1,0
If KeyDown(205) Then TurnEntity camera,0,-1,0
RenderWorld
Text 0,0,"Arrow keys: move camera Space: free the left instance Esc: exit"
Text 0,20,"CreatePrefabDocument made the lamp post; the right one is a CopyEntity"
Text 0,40,"CountOwnedEntities(copy) = "+CountOwnedEntities(copy)+" first part: "+PrefabPartID(GetOwnedEntity(copy,1))
Text 0,60,"PrefabSourceID(copy) = "+PrefabSourceID(copy)
; An unsaved prefab reports a synthetic untitled path; show its end
source_path$=PrefabSourcePath(copy)
Text 0,80,"PrefabSourcePath(copy) ends: ..."+Right(source_path,40)
If released
Text 0,100,"The left instance and its detached lamp are gone"
Else
Text 0,100,"EntityOwner(detached lamp) is the left instance: "+(EntityOwner(lamp)=original)
EndIf
Flip
Wend
FreeWorld world
End