| instance - prefab placement or owned part |
|
Returns the resource file that declared a prefab instance. The result is empty for an ordinary entity. Embedded definitions use their containing document path. This is provenance, not a unique resource ID. For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow. See also: PrefabSourceID, PrefabPartID, FindPrefabPart. |
; 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