Blitz3D+ Command Reference

SetWorldEditorViewSelection view,entity_id:Long[,additive]

Parameters

view - World Editor view handle

entity_id:Long - opaque session entity ID, or zero to clear the selection

additive (optional) - False replaces the selection (default); True adds the entity to it

Description

Sets the selection highlighted by the debug host.

The selection is drawn in the same 3D space as the real world. Bounds are drawn for every selected entity; the most recently added entity owns the axes. A repeated ID becomes active without being added twice. Zero clears the entire selection even when additive is True. Up to 4,096 IDs may be selected.

Changes are sent with the next RenderWorldEditorView call, not synchronously. Freed or stale entity IDs are ignored by the host. Selection does not change entity transforms or the live world's mutation revision and is available while running or paused. Multi-selection requires the host capability view.multi-selection.v1; existing two-argument calls retain their single-selection behaviour.

Handles are context-owned and reject stale or wrong-kind values.

For the full story, see the Debug World Editor guide.

Requires Extended mode.

See also: PickWorldEditorView, WorldEditorViewBounds, WorldEditorSessionCapabilities.

Example

; OpenWorldEditorSession Example
; ------------------------------
; Requires Extended mode.

; A minimal custom World Editor client. DebugWorld launches this program
; with a --session descriptor; it opens the session, shows a live view,
; and demonstrates the whole session/view/request family.

Const EVENT_MOUSE_DOWN=$201
Const EVENT_GADGET_ACTION=$401
Const EVENT_WINDOW_CLOSE=$803

descriptor$=SessionArgument()
If descriptor="" Then RuntimeError "This custom editor must be launched by DebugWorld"

; The short-lived descriptor is consumed and authenticated exactly once
session=OpenWorldEditorSession(descriptor)
If session=0 Then RuntimeError WorldEditorSessionError()

; The negotiated capability object tells the client what the host supports
capabilities=WorldEditorSessionCapabilities(session)
capability_count=JsonCount(capabilities)
FreeJson capabilities

window=CreateWindow("Custom World Editor",100,100,800,560,0,15)
canvas=CreateCanvas(0,64,ClientWidth(window),ClientHeight(window)-64,window)
SetGadgetLayout canvas,1,1,1,1
pause_button=CreateButton("Pause",8,6,90,24,window)
continue_button=CreateButton("Continue",106,6,90,24,window)
projection_button=CreateButton("Orthographic",204,6,120,24,window)
follow_button=CreateButton("Look through pick",332,6,140,24,window)
status_label=CreateLabel("Session opened; capabilities: "+capability_count,8,36,780,20,window)

; Bind a live host-rendered view to the canvas and place its free camera
view=CreateWorldEditorView(session,canvas)
SetWorldEditorViewCamera view,0,3,-8,0.2,0,5
projection=1
SetWorldEditorViewProjection view,projection,24,True

running=True
request=0
request_kind$=""
last_pick$=""
following=False
status$="Click the view to pick an entity"

While running

    event=WaitEvent(16)

    If event=EVENT_WINDOW_CLOSE Then running=False

    If event=EVENT_GADGET_ACTION And EventSource()=projection_button
        ; Toggle between perspective (1) and orthographic (2) projection
        projection=3-projection
        SetWorldEditorViewProjection view,projection,24,True
        If projection=1 Then SetGadgetText projection_button,"Orthographic" Else SetGadgetText projection_button,"Perspective"
    EndIf

    ; Render through the last picked entity (pick a camera first), or back
    ; through the detached editor camera
    If event=EVENT_GADGET_ACTION And EventSource()=follow_button
        following=Not following
        If following And last_pick<>""
            SetWorldEditorViewEntity view,Long(last_pick)
            SetGadgetText follow_button,"Editor camera"
        Else
            following=False
            SetWorldEditorViewEntity view,0
            SetGadgetText follow_button,"Look through pick"
        EndIf
    EndIf

    If event=EVENT_GADGET_ACTION And request=0
        ; Pause/Continue are asynchronous value-only requests to the host
        If EventSource()=pause_button Or EventSource()=continue_button
            payload=CreateJsonObject()
            If EventSource()=pause_button Then request=SendWorldEditorRequest(session,"pause",payload)
            If EventSource()=continue_button Then request=SendWorldEditorRequest(session,"continue",payload)
            FreeJson payload
            request_kind="action"
        EndIf
    EndIf

    If event=EVENT_MOUSE_DOWN And EventSource()=canvas And request=0
        ; Queue an engine-camera pick at the clicked canvas pixel
        request=PickWorldEditorView(view,EventX(),EventY())
        request_kind="pick"
    EndIf

    ; Service the outstanding request without blocking
    If request<>0 And WorldEditorRequestState(request)>=WORLD_EDITOR_REQUEST_SUCCEEDED
        result=WorldEditorRequestResult(request)
        If result=0
            status=request_kind+" request: "+WorldEditorRequestError(request)
            FreeWorldEditorRequest request
            request=0
        Else
            picked_id$=MemberText(result,"id")
            FreeJson result
            FreeWorldEditorRequest request
            request=0
            If request_kind="pick" And picked_id<>""
                ; Highlight the picked entity and ask for its framing bounds
                SetWorldEditorViewSelection view,Long(picked_id)
                request=WorldEditorViewBounds(view,Long(picked_id))
                request_kind="bounds"
                status="Picked entity "+picked_id
                last_pick=picked_id
            ElseIf request_kind="bounds"
                status=status+" - bounds received"
            Else
                status=request_kind+" request succeeded"
            EndIf
        EndIf
    EndIf

    ; Session events (hierarchy changes, host notifications) arrive as JSON
    session_event=PollWorldEditorEvent(session)
    If session_event<>0
        status="Event: "+Left(JsonStringify(session_event),60)
        FreeJson session_event
    EndIf

    ; Show live session health and both observed revisions
    state=WorldEditorSessionState(session)
    If state=WORLD_EDITOR_SESSION_CLOSED Then running=False
    If state=WORLD_EDITOR_SESSION_FAILED
        status="Session failed: "+WorldEditorSessionError(session)
        running=False
    EndIf
    If WorldEditorViewState(view)=WORLD_EDITOR_VIEW_FAILED Then status="View failed: "+WorldEditorViewError(view)
    SetGadgetText status_label,"State "+state+"  Revision "+WorldEditorSessionRevision(session)+"  Hierarchy "+WorldEditorSessionHierarchyRevision(session)+"  |  "+status

    RenderWorldEditorView view

Wend

; An unfinished request can be cancelled before its host operation commits
If request<>0
    CancelWorldEditorRequest request
    FreeWorldEditorRequest request
EndIf
FreeWorldEditorView view
CloseWorldEditorSession session
FreeGadget window

End

; Extract the descriptor that DebugWorld passes after --session
Function SessionArgument$()
    command$=CommandLine$()
    position=Instr(Lower(command),"--session")
    If position=0 Then Return ""
    position=position+9
    While position<=Len(command) And Mid(command,position,1)=" "
        position=position+1
    Wend
    If Mid(command,position,1)=Chr(34)
        finish=Instr(command,Chr(34),position+1)
        Return Mid(command,position+1,finish-position-1)
    EndIf
    Return Mid(command,position)
End Function

; Read one string member from a caller-owned JSON object
Function MemberText$(json,key$)
    If JsonObjectHas(json,key)=0 Then Return ""
    member=JsonObjectGet(json,key)
    If member=0 Then Return ""
    value$=JsonText(member)
    FreeJson member
    Return value
End Function

Index