|
world_document - world document handle entity_id$ - ID of the authored root entity; its descendants are included file$ (optional) - destination path and dependency base; "" leaves it untitled (default) |
|
Creates a prefab resource document from part of a world document. Turn a lamp post, a door with its frame, or any authored group into a reusable prefab. The result is a new dirty prefab document with a fresh resource ID; the source world is unchanged and no file is written until SaveResourceDocument. The selected root becomes the prefab origin. Shared media and nested resource references are retained. Bindings to scene entities/components outside the selection become required typed inputs, and their scene IDs are never saved; inspect definition.inputs before placing the result. Free the returned handle with FreeResourceDocument. For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow. See also: CreateResourceDocument, SaveResourceDocument, FindPrefabPart, PrefabInputsBound, FreeResourceDocument. |
; 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