UI

May 30, 2024 · View on GitHub

from tdw.add_ons.ui import UI

Manager add-on for UI in TDW.

Parameter types

All parameters of type Dict[str, float] are Vector2, e.g. {"x": 0, "y": 0}. There is no "z" parameter.

"x" is the horizontal value and "y" is the vertical value.

In some cases, this document will note that Vector2 values must be integers. This is usually because they are adjusting a value that references the actual screen pixels.

Fields

commands These commands will be appended to the commands of the next communicate() call.
initialized If True, this module has been initialized.

Functions

init

UI()

UI(canvas_id=0)

Parameter	Type	Default	Description
canvas_id	int	0	The ID of the UI canvas.

get_initialization_commands

self.get_initialization_commands()

This function gets called exactly once per add-on. To re-initialize, set self.initialized = False.

Returns: A list of commands that will initialize this add-on.

on_send

self.on_send(resp)

This is called within Controller.communicate(commands) after commands are sent to the build and a response is received.

Use this function to send commands to the build on the next Controller.communicate(commands) call, given the resp response. Any commands in the self.commands list will be sent on the next Controller.communicate(commands) call.

Parameter	Type	Default	Description
resp	List[bytes]		The response from the build.

before_send

self.before_send(commands)

This is called within Controller.communicate(commands) before sending commands to the build. By default, this function doesn't do anything.

Parameter	Type	Default	Description
commands	List[dict]		The commands that are about to be sent to the build.

get_early_initialization_commands

self.get_early_initialization_commands()

This function gets called exactly once per add-on. To re-initialize, set self.initialized = False.

These commands are added to the list being sent on communicate() before any other commands, including those added by the user and by other add-ons.

Usually, you shouldn't override this function. It is useful for a small number of add-ons, such as loading screens, which should initialize before anything else.

Returns: A list of commands that will initialize this add-on.

add_text

self.add_text(text, font_size, position)

self.add_text(text, font_size, position, anchor=None, pivot=None, color=None, raycast_target=True)

Add UI text to the scene.

Parameter	Type	Default	Description
text	str		The text.
font_size	int		The size of the font.
position	Dict[str, int]		The screen (pixel) position as a Vector2. Values must be integers.
anchor	Dict[str, float]	None	The anchor as a Vector2. Values are floats between 0 and 1. If None, defaults to `{"x": 0.5, "y": 0.5}`.
pivot	Dict[str, float]	None	The pivot as a Vector2. Values are floats between 0 and 1. If None, defaults to `{"x": 0.5, "y": 0.5}`.
color	Dict[str, float]	None	The color of the text. If None, defaults to `{"r": 1, "g": 1, "b": 1, "a": 1}`.
raycast_target	bool	True	If True, raycasts will hit the UI element.

Returns: The ID of the new UI element.

add_image

self.add_image(image, position, size)

self.add_image(image, position, size, rgba=True, scale_factor=None, anchor=None, pivot=None, color=None, raycast_target=True)

Add a UI image to the scene.

Parameter	Type	Default	Description
image	Union[str, Path, bytes, Image.Image]		The image. If a string or `Path`, this is a filepath. If `bytes`, this is the image byte data. If `Image.Image`, this is a PIL image.
position	Dict[str, int]		The screen (pixel) position as a Vector2. Values must be integers.
size	Dict[str, int]		The pixel size of the image as a Vector2. Values must be integers and must match the actual image size.
rgba	bool	True	If True, this is an RGBA image. If False, this is an RGB image.
scale_factor	Dict[str, float]	None	Scale the UI image by this factor. If None, defaults to {"x": 1, "y": 1}.
anchor	Dict[str, float]	None	The anchor as a Vector2. Values are floats between 0 and 1. If None, defaults to `{"x": 0.5, "y": 0.5}`.
pivot	Dict[str, float]	None	The pivot as a Vector2. Values are floats between 0 and 1. If None, defaults to `{"x": 0.5, "y": 0.5}`.
color	Dict[str, float]	None	The color of the text. If None, defaults to `{"r": 1, "g": 1, "b": 1, "a": 1}`.
raycast_target	bool	True	If True, raycasts will hit the UI element.

Returns: The ID of the new UI element.

add_cutout

self.add_cutout(base_id, image, position, size)

self.add_cutout(base_id, image, position, size, scale_factor=None, anchor=None, pivot=None)

Add a UI image that cuts a transparent hole in another UI image.

Parameter	Type	Default	Description
base_id	int		The ID of the image that will have a hole in it. This can be added on the same frame as the cutout image but it must be added prior to the cutout image.
image	Union[str, Path, bytes, Image.Image]		The image. This must be an RGBA image. If a string or `Path`, this is a filepath. If `bytes`, this is the image byte data. If `Image.Image`, this is a PIL image.
position	Dict[str, int]		The screen (pixel) position as a Vector2. Values must be integers.
size	Dict[str, int]		The pixel size of the image as a Vector2. Values must be integers and must match the actual image size.
scale_factor	Dict[str, float]	None	Scale the UI image by this factor. If None, defaults to {"x": 1, "y": 1}.
anchor	Dict[str, float]	None	The anchor as a Vector2. Values are floats between 0 and 1. If None, defaults to `{"x": 0.5, "y": 0.5}`.
pivot	Dict[str, float]	None	The pivot as a Vector2. Values are floats between 0 and 1. If None, defaults to `{"x": 0.5, "y": 0.5}`.

Returns: The ID of the new UI element.

set_text

self.set_text(ui_id, text)

Set the text of a UI text element that is already in the scene.

Parameter	Type	Default	Description
ui_id	int		The ID of the UI text element.
text	str		The text.

attach_canvas_to_avatar

self.attach_canvas_to_avatar()

self.attach_canvas_to_avatar(avatar_id="a", focus_distance=2.5, plane_distance=0.101)

Attach the UI canvas to an avatar. This allows the UI to appear in image output data.

Parameter	Type	Default	Description
avatar_id	str	"a"	The avatar ID.
focus_distance	float	2.5	The focus distance. If the focus distance is less than the default value (2.5), the UI will appear blurry unless post-processing is disabled.
plane_distance	float	0.101	The distance from the camera to the UI canvas. This should be slightly further than the near clipping plane.

attach_canvas_to_vr_rig

self.attach_canvas_to_vr_rig()

self.attach_canvas_to_vr_rig(plane_distance=0.25)

Attach the UI canvas to a VR rig.

Parameter	Type	Default	Description
plane_distance	float	0.25	The distance from the camera to the UI canvas.

set_position

self.set_position(ui_id, position)

Set the position of a UI element.

Parameter	Type	Default	Description
ui_id	int		The UI element's ID.
position	Dict[str, float]		The screen (pixel) position as a Vector2. Values must be integers.

set_size

self.set_size(ui_id, size)

Set the size of a UI element that is already in the scene.

Parameter	Type	Default	Description
ui_id	int		The ID of the UI element.
size	Dict[str, float]		The size.

set_rotation

self.set_rotation(ui_id, angle)

Rotate a UI element to an angle.

Parameter	Type	Default	Description
ui_id	int		The ID of the UI element.
angle	float		The new rotation angle in degrees.

set_depth

self.set_depth(ui_id, depth)

Set the depth (z value) of a UI element relative its canvas (not its camera).

If the canvas is attached to an avatar or VR rig, the canvas depth relative to the camera is the plane_distance.

Parameter	Type	Default	Description
ui_id	int		The UI element's ID.
depth	float		The depth (z value) in meters.

destroy

self.destroy(ui_id)

Destroy a UI element.

Parameter	Type	Default	Description
ui_id	int		The ID of the UI element.

destroy_all

self.destroy_all()

self.destroy_all(destroy_canvas=False)

Destroy all UI elements.

Parameter	Type	Default	Description
destroy_canvas	bool	False	If True, destroy the UI canvas and all of its UI elements. If False, destroy the canvas' UI elements but not the canvas itself.