PrefabSourcePath$ ( instance )

Parameters

instance - prefab placement or owned part

Description

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.

Requires Extended mode.

See also: PrefabSourceID, PrefabPartID, FindPrefabPart.

Example

; CreatePrefabDocument Example
; ----------------------------
; Requires Extended mode.

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

Index

Blitz3D+ Command Reference

PrefabSourcePath$ ( instance )

Parameters

Description

Example