====== vci.studio(ExportStudio)&(Scripts for preset items) ======

A function required to get pieces of information in the studio.\\
It is generally used for acquiring state of items and performing operation on items from VCI script.\\
For information on items in VirtualCast, refer to [[en:virtualcast:top|VirtualCast TOP]].

===== List of functions =====

**For the latest list of the functions, refer to "types.lua" file in "EmbeddedScriptWorkspace" folder. **

==== ExportStudio ====

Has functions and Get functions exist for each of the preset items in VirtualCast.\\
Has function is a function to check if the item exist in the studio and Get function is a function to acquire the instance of an item.\\
Using Get on items that don't exist in the studio will give you null, so only use Get when the result of the Has function is true.\\
Note that, as of 29th August 2019, items that can also be spawned by guests cannot be acquired.

^ Function ^ Description ^
| shared | [[en:vci:script:reference:exportshared| vci.studio.shared(ExportShared)]] |
| GetOwner fun(): ExportAvatar | Acquire the [[en:vci:script:reference:exportavatar|avatar]] of the VCI owner |
| GetAvatars fun(): ExportAvatar | Acquire the list of [[en:vci:script:reference:exportavatar|avatars]] in the studio |
| GetMic fun(): ExportSystemItem | Instantiate a [[en:virtualcast:studio:item:microphone|microphone]] |
| HasMic fun(): bool | True when a [[en:virtualcast:studio:item:microphone|microphone]] exists in the studio |
| GetLightSource fun(): ExportSystemItem | Instantiate a [[virtualcast:studio:item:lightsource|lightsource]] |
| HasLightSource fun(): bool | True when a [[en:virtualcast:studio:item:lightsource|lightsource]] exists in the studio |
| GetMirror fun(): ExportSystemItem | Instantiate a [[en:virtualcast:studio:item:mirror|mirror]] |
| HasMirror fun(): bool | True when a [[en:virtualcast:studio:item:mirror|mirror]] exists in the studio |
| GetHarisen fun(): ExportSystemItem | Instantiate a [[en:virtualcast:studio:item:harisen|fan]] |
| HasHarisen fun(): bool | True when a [[en:virtualcast:studio:item:harisen|fan]] exists in the studio |
| GetMosaic fun(): ExportSystemItem | Instantiate a [[en:virtualcast:studio:item:mosaic|mosaic]] |
| HasMosaic fun(): bool| True when a [[en:virtualcast:studio:item:mosaic|mosaic]] exists in the studio |
| GetHammer fun(): ExportSystemItem | Instantiate a [[en:virtualcast:studio:item:picopicohammer|squeaky hammer]] |
| HasHammer fun(): bool | True when a [[en:virtualcast:studio:item:picopicohammer|squeaky hammer]] exists in the studio |
| GetWindowCamera fun(): ExportSystemCamera | Instantiate a [[en:virtualcast:studio:item:monitorcamera|camera monitor]] |
| HasWindowCamera fun(): bool | True when a [[en:virtualcast:studio:item:monitorcamera|camera monitor]] exists in the studio |
| GetHandiCamera fun(): ExportSystemCamera | Instantiate a [[en:virtualcast:studio:item:handycamera|handy camera]] |
| HasHandiCamera fun(): bool | True when a [[en:virtualcast:studio:item:handycamera|handy camera]] exists in the studio |
| GetAutoFollowCamera fun(): ExportSystemCamera | Instantiate a [[en:virtualcast:studio:item:followingcamera|tracking Camera]] |
| HasAutoFollowCamera fun(): bool | True when a [[en:virtualcast:studio:item:followingcamera|tracking camera]] exists in the studio |
| GetSwitchingCamera fun(): ExportSystemCamera | Instantiate a [[en:virtualcast:studio:item:switchingcamera|switching camera]] |
| HasSwitchingCamera fun(): bool | True when a [[en:virtualcast:studio:item:switchingcamera|switching camera]] exists in the studio |
| GetNameBoard fun(idOrName: string): ExportSystemItem | Instantiate the name plate. Specify the user name or ID acquired from [[en:vci:script:reference:exportavatar|ExportAvatar]]. |
| HasNameBoard fun(idOrName: string): bool | true if the name plate exists in the studio |

==== SystemItem ====

^ Function ^ Description ^
| GetName fun(): string | Get the name of an item.
| GetLocalPosition fun(): Vector3 | Get the position of an item\\ (The origin point is the local coordinate at the time of spawn ) |
| GetPosition fun(): Vector3 | Get the position of an item\\ (The origin point is (0,0,0) of the world coordinate) |
| GetLocalRotation fun(): Quaternion | Get the rotation of an item\\ (The basis is the attitude at the time of spawn) |
| GetRotation fun(): Quaternion | Get the rotation of an item\\ (Based on the world coordinate) |
| GetLocalScale fun(): Vector3 | Get the scale of an item |
| GetRight fun(): Vector3 | The vector of the right direction (+X) of an item |
| GetUp fun(): Vector3 | The vector of the up direction (+Y) of an item |
| GetForward fun(): Vector3 | The vector of the forward direction (+Z) of an item |
| GetLocalToWorldMatrix fun(): Matrix4x4 | Matrix when converting from the local coordinate to the world coordinate of an item |
| SetPosition fun(position: Vector3): number | Change the position of an item\\ (World coordinate) ** *1** |
| SetRotation fun(rotation: Quaternion): number | Change the rotation of an item\\ (World coordinate) ** *1** |
| SetLocalPosition fun(localPosition: Vector3): number | Change the position of an item\\ (Local coordinate) ** *1** |
| SetLocalRotation fun(localRotation: Quaternion): number | Change the rotation of an item\\ (Local coordinate) ** *1** |
| IsGrabbed fun(): bool | True when grabbed |

** *1**\\
''SetPosition'' ''SetRotation'' ''SetLocalPosition'' ''SetLocalRotation'' are **only executable from VCIs spawned by the room owner themself.\\ **\\


==== ExportSystemCamera ====

It's basically the same with the SystemItem, but there exists some functions unique to the camera.\\

^ Function ^ Description ^
| GetFieldOfView fun(): number | Get the field of view (FOV) of the camera |
| SetFieldOfView fun(fov: number): number | Change the field of view (FOV) of the camera ** *1** ** *2** |
| GetMinFieldOfView fun(): number | Get the minimum field of view (FOV) of the camera |
| GetMaxFieldOfView fun(): number | Get the maximum field of view (FOV) of the camera |
| GetName fun(): string | Get the name of an item.
| GetLocalPosition fun(): Vector3 | Get the position of an item\\ (The origin point is the local coordinate at the time of spawn ) |
| GetPosition fun(): Vector3 | Get the position of an item\\ (The origin point is (0,0,0) of the world coordinate) |
| GetLocalRotation fun(): Quaternion | Get the rotation of an item\\ (The basis is the attitude at the time of spawn) |
| GetRotation fun(): Quaternion | Get the rotation of an item\\ (Based on the world coordinate) |
| GetLocalScale fun(): Vector3 | Get the scale of an item |
| GetRight fun(): Vector3 | The vector of the right direction (+X) of an item |
| GetUp fun(): Vector3 | The vector of the up direction (+Y) of an item |
| GetForward fun(): Vector3 | The vector of the forward direction (+Z) of an item |
| GetLocalToWorldMatrix fun(): Matrix4x4 | Matrix when converting from the local coordinate to the world coordinate of an item |
| SetPosition fun(position: Vector3): number | Change the position of an item\\ (World coordinate) ** *1** |
| SetRotation fun(rotation: Quaternion): number | Change the rotation of an item\\ (World coordinate) ** *1** |
| SetLocalPosition fun(localPosition: Vector3): number | Change the position of an item\\ (Local coordinate) ** *1** |
| SetLocalRotation fun(localRotation: Quaternion): number | Change the rotation of an item\\ (Local coordinate) ** *1** |
| IsGrabbed fun(): bool | True when grabbed |

** *1**\\
''SetPosition'', ''SetRotation'', ''SetLocalPosition'', ''SetLocalRotation'' and "SetFieldOfView" are **only executable from VCIs spawned by the room owner themself.\\ **\\

** *2**\\
Bellow is the list of the cameras that can have the FOV specified. You cannot specify a value that exceeds the value acquirable with ''GetMinFieldOfView'' and ''GetMaxFieldOfView.''

^ Camera name ^ FOV setting ^
| Camera monitor | No |
| Handy camera | Yes |
| Tracking camera | Yes |
| Switching camera | No |

===== Summary =====

Example\\

<file lua main.lua>
function onUse(use)
    -- When PositionReset is used
    if use == "CameraPositionReset" then
        -- Reset the position of the camera
        CameraPositionReset()
    end
end

function CameraPositionReset()
    -- End if handy camera doesn't exist
    if vci.studio.HasHandiCamera() == false then
        print("Handy camera doesn't exist. End.")
        return
    end

    -- The coordinate to reset
    local position = Vector3.__new(0, 1, 0)
    -- Instance of the camera
    local camera = vci.studio.GetHandiCamera()
    -- Change the position of the camera
    camera.SetPosition(position)
    print("Camera position　："..tostring(camera.GetPosition()))
end
</file>

The result\\

<code lua>
Camera position : (0,1,0)
(The camera moves to (0,1,0) in the world coordinate)
</code>


**Explanation**\\

In this example, the position of the [[en:virtualcast:studio:item:handycamera|handy camera]] is reset to (0,1,0) when a SubItem called CameraPositionReset is reset.\\

<code lua>
    if vci.studio.HasHandiCamera() == false then
        print("Handy camera doesn't exist. End.")
        return
    end
</code>

Executing ''vci.studio.GetHandiCamera()'' when the handy camera is non-existent in the studio will cause an error.\\
So when ''vci.studio.HasHandiCamera() == false'' (handy camera doesn't exist), it returns to end the process.\\
\\
When ''vci.studio.HasHandiCamera() == true'', the return will not be executed and it reaches ''camera.SetPosition(position)'', which will reset the camera.\\
Therefore, **you must always use Has function to check the existence of an item before instantiating an item with Get function**.\\
\\
It's a case-by-case, but it is recommended to use **when Has function is false, then return** idiom.\\
While there is no big deal with **when true, then do this** strategy, it tends to result in variables being kept inside the scope of the if statement. It could also result in if statements nested inside the if statement.\\
**When Has function is false, then don't do this" is more definitive, so we recommend you to bring this in the front.\\
This way of writing a program is called the Guard.