版本：最新版 - a1.156.0 ⚖️

🖼️ Canvas

画布是一个你可以在其上进行绘制的实体。

👪Inheritance

This class shares methods and events from Base Entity.

🎒 示例

Client/Index.lua
-- Spawns a Canvas
local my_canvas = Canvas(
  true,
  Color.TRANSPARENT,
  0,
  true
)

-- Subscribes for Update, we can only Draw inside this event
my_canvas:Subscribe("Update", function(self, width, height)
  -- Draws a Text in the middle of the screen
  self:DrawText("Hello World!", Vector2D(width / 2, height / 2))

  -- Draws a red line Horizontally
  self:DrawLine(Vector2D(0, height / 2), Vector2D(width, height / 2), 10, Color.RED)
end)

-- Forces the canvas to repaint, this will make it trigger the Update event
my_canvas:Repaint()

-- Applies the Canvas as the material of a (client side) StaticMesh
local my_mesh = StaticMesh(Vector(0, 0, 100), Rotator(), "nanos-world::SM_Cube")
my_mesh:SetMaterialFromCanvas(my_canvas)

提示

You can use the output Texture from a Canvas with :SetMaterialFromCanvas() method!

🛠 构造函数

Default Constructor

No description provided

local my_canvas = Canvas(is_visible?, clear_color?, auto_repaint_rate?, should_clear_before_update?, auto_resize?, width?, height?, screen_position?)

Parameters

Type	Name	Default	Description
boolean	`is_visible`	`true`	是否将其绘制在屏幕上
Color	`clear_color`	`Color.TRANSPARENT`	用于清除画布的颜色（背景颜色）
float	`auto_repaint_rate`	`-1`	自动重绘的频率（调用 Update 事件），传入 0 表示每一帧都重绘，传入 -1 表示禁用
boolean	`should_clear_before_update`	`true`	是否在更新前使用清除颜色进行画布清除
boolean	`auto_resize`	`true`	随屏幕大小自动调整尺寸
integer	`width`	`0`	如果不使用 auto_resize
integer	`height`	`0`	如果不使用 auto_resize
Vector2D	`screen_position`	`Vector2D(0, 0)`	如果不使用 auto_resize，在绘制到屏幕时的偏移量

🗿 静态函数

Inherited Entity Static Functions

Canvas inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity

Returns	Name	Description
table of Base Entity	`GetAll`	返回一个包含调用此方法的类中所有实体的表
Base Entity	`GetByIndex`	返回该类中指定索引处的特定实体
integer	`GetCount`	返回该类当前存在的实体数量
table of table	`GetInheritedClasses`	获取使用继承系统创建的、直接继承自该类的所有子类列表
iterator	`GetPairs`	返回一个包含该类所有实体的迭代器，用于 `pairs()` 循环
table or nil	`GetParentClass`	如果该类是使用继承系统创建的，则获取其父类
table	`Inherit`	使用继承系统继承此类
boolean	`IsChildOf`	如果该类是使用继承系统创建的，检查此类是否为另一个类的子类
function	`Subscribe`	为该类的所有实体订阅一个事件
function	`SubscribeRemote`	订阅从服务器调用的自定义远程事件
	`Unsubscribe`	退订此包内该类中此事件的所有回调，或者仅取消传入的特定回调

This class doesn't have own static functions.

🦠 函数

Inherited Entity Functions

Canvas inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity

Returns	Name	Description
	`BroadcastRemoteEvent`	直接在此实体上向所有玩家调用自定义远程事件
	`BroadcastRemoteInRadiusEvent`	直接针对此实体调用自定义远程事件，并将该事件传递给半径范围内的所有玩家
	`CallRemoteEvent`	直接在此实体上向特定玩家调用自定义远程事件
	`CallRemoteEvent`	直接在此实体上调用自定义远程事件
	`CallRemotePlayersEvent`	直接在此实体上调用自定义远程事件，并将事件传递给玩家列表
	`Destroy`	销毁该实体
	`FinishSpawn`	如果此实体是以延迟 `spawn_mode` 生成的，则完成生成过程并将该实体发送至客户端
table of string	`GetAllValuesKeys`	获取所有存储值的键名列表
table	`GetClass`	获取该实体的类
integer	`GetID`	获取该实体的全网通用网络 ID（在客户端和服务器上相同）
any	`GetValue`	获取此实体上存储在给定键处的值
boolean	`HasAuthority`	获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）
boolean	`IsA`	递归检查此实体是否继承自某个类
boolean	`IsBeingDestroyed`	如果该实体正在被销毁，则返回 true
boolean	`IsSpawned`	获取此实体是否已完成生成
boolean	`IsValid`	如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true
	`SetSpawnMode`	从继承类的构造函数中覆盖此实体完成生成的时间点
	`SetValue`	在此实体中设置一个值
function	`Subscribe`	在这个特定实体上订阅一个事件
function	`SubscribeRemote`	在这个特定实体上订阅一个从服务器调用的自定义远程事件
	`Unsubscribe`	退订此包内该实体中此事件的所有回调，或者仅取消传入的特定回调

Returns	Name	Description
	`Clear`	使用特定颜色清除画布
	`DrawBox`	在画布上绘制一个未填充的方框
	`DrawLine`	在画布上绘制一条线
	`DrawMaterial`	在画布上绘制材质
	`DrawMaterialFromSceneCapture`	在画布上绘制 SceneCapture
	`DrawMaterialFromWebUI`	在画布上绘制 WebUI
	`DrawPolygon`	在画布上绘制一个 N 多边形
	`DrawRect`	在画布上绘制一个填充后的矩形
	`DrawText`	在画布上绘制文本
	`DrawTexture`	在画布上绘制纹理
Vector2D	`GetSize`	获取画布大小
	`Repaint`	强制重绘
	`Resize`	如果不使用 auto_resize，调整画布大小
	`SetAutoRepaintRate`	设置重绘率
	`SetAutoResize`	设置画布是否应根据屏幕大小自动调整尺寸
	`SetScreenPosition`	设置画布屏幕位置的偏移量
	`SetVisibility`	设置其在屏幕上是否可见

Optimal

`Clear`

使用特定颜色清除画布

my_canvas:Clear(clear_color)

Parameters

Type	Parameter	Default	Description
Color	`clear_color`	Required parameter	用于填充画布的颜色

Moderate

`DrawBox`

在画布上绘制未填充的方框

此方法只能在 Update 事件内部调用

my_canvas:DrawBox(screen_position, screen_size, thickness, render_color?, blend_mode?)

Parameters

Type	Parameter	Default	Description
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`screen_size`	Required parameter	在画布上的尺寸（像素）
float	`thickness`	Required parameter	线条粗细
Color	`render_color?`	`Color.WHITE`	绘制图形的色调
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawLine`

在画布上绘制一条直线

此方法只能在 Update 事件内部调用

my_canvas:DrawLine(screen_position_a, screen_position_b, thickness, render_color, blend_mode?)

Parameters

Type	Parameter	Default	Description
Vector2D	`screen_position_a`	Required parameter	线条的起点位置（像素）
Vector2D	`screen_position_b`	Required parameter	线条的终点位置（像素）
float	`thickness`	Required parameter	线条粗细
Color	`render_color`	Required parameter	绘制图形的色调
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawMaterial`

在画布上绘制材质

此方法只能在 Update 事件内部调用

注：由于虚幻引擎处理渲染目标的机制，在画布上绘制材质会导致奇怪的半透明效果。希望日后能得到改善。

my_canvas:DrawMaterial(material_path, screen_position, screen_size, coordinate_position, coordinate_size?, rotation?, pivot_point?, blend_mode?)

Parameters

Type	Parameter	Default	Description
Material Reference	`material_path`	Required parameter	要使用的材质资产
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`screen_size`	Required parameter	在画布上的尺寸（像素）
Vector2D	`coordinate_position`	Required parameter	要绘制源内容的左上角 UV 坐标（0 到 1）
Vector2D	`coordinate_size?`	`Vector2D(1, 1)`	要绘制源内容的 UV 尺寸（0 到 1），使用 (1, 1) 表示整个源内容
float	`rotation?`	`0`	旋转（度）
Vector2D	`pivot_point?`	`Vector2D(0.5, 0.5)`	旋转轴心点，相对于绘制尺寸（0.5, 0.5 为中心）
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawMaterialFromSceneCapture`

在画布上绘制 SceneCapture

此方法只能在 Update 事件内部调用

注：由于虚幻引擎处理渲染目标的机制，在画布上绘制材质会导致奇怪的半透明效果。希望日后能得到改善。

my_canvas:DrawMaterialFromSceneCapture(scenecapture_entity, screen_position, screen_size, coordinate_position, coordinate_size?, rotation?, pivot_point?, blend_mode?)

Parameters

Type	Parameter	Default	Description
SceneCapture	`scenecapture_entity`	Required parameter	要绘制的 SceneCapture
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`screen_size`	Required parameter	在画布上的尺寸（像素）
Vector2D	`coordinate_position`	Required parameter	要绘制源内容的左上角 UV 坐标（0 到 1）
Vector2D	`coordinate_size?`	`Vector2D(1, 1)`	要绘制源内容的 UV 尺寸（0 到 1），使用 (1, 1) 表示整个源内容
float	`rotation?`	`0`	旋转（度）
Vector2D	`pivot_point?`	`Vector2D(0.5, 0.5)`	旋转轴心点，相对于绘制尺寸（0.5, 0.5 为中心）
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawMaterialFromWebUI`

在画布上绘制 WebUI

此方法只能在 Update 事件内部调用

注：由于虚幻引擎处理渲染目标的机制，在画布上绘制材质会导致奇怪的半透明效果。希望日后能得到改善。

my_canvas:DrawMaterialFromWebUI(webui_entity, screen_position, screen_size, coordinate_position, coordinate_size?, rotation?, pivot_point?, blend_mode?)

Parameters

Type	Parameter	Default	Description
WebUI	`webui_entity`	Required parameter	要绘制的 WebUI
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`screen_size`	Required parameter	在画布上的尺寸（像素）
Vector2D	`coordinate_position`	Required parameter	要绘制源内容的左上角 UV 坐标（0 到 1）
Vector2D	`coordinate_size?`	`Vector2D(1, 1)`	要绘制源内容的 UV 尺寸（0 到 1），使用 (1, 1) 表示整个源内容
float	`rotation?`	`0`	旋转（度）
Vector2D	`pivot_point?`	`Vector2D(0.5, 0.5)`	旋转轴心点，相对于绘制尺寸（0.5, 0.5 为中心）
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawPolygon`

在画布上绘制 N 边形

此方法只能在 Update 事件内部调用

my_canvas:DrawPolygon(texture_path, screen_position, radius?, number_of_sides?, render_color?, blend_mode?)

Parameters

Type	Parameter	Default	Description
Image Path	`texture_path`	Required parameter	传入空字符串以使用默认的白色纹理
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`radius?`	`Vector2D(1, 1)`	多边形在各个轴上的半径（像素）
integer	`number_of_sides?`	`3`	多边形拥有多少条边
Color	`render_color?`	`Color.WHITE`	绘制图形的色调
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawRect`

在画布上绘制实心矩形

此方法只能在 Update 事件内部调用

my_canvas:DrawRect(texture_path, screen_position, screen_size, render_color?, blend_mode?)

Parameters

Type	Parameter	Default	Description
Image Path	`texture_path`	Required parameter	传入空字符串以使用默认的白色纹理
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`screen_size`	Required parameter	在画布上的尺寸（像素）
Color	`render_color?`	`Color.WHITE`	绘制图形的色调
BlendMode	`blend_mode?`	`BlendMode.Opaque`	与已有绘制内容的混合方式

Moderate

`DrawText`

在画布上绘制文本

此方法只能在 Update 事件内部调用

使用透明的 clear_color 时，阴影和描边无法正常工作

my_canvas:DrawText(text, screen_position, font_type?, font_size?, text_color?, kerning?, center_x?, center_y?, shadow_color?, shadow_offset?, outlined?, outline_color?)

Parameters

Type	Parameter	Default	Description
string	`text`	Required parameter	要绘制的文本
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
FontType	`font_type?`	`FontType.Roboto`	要使用的字体
integer	`font_size?`	`12`	字号尺寸
Color	`text_color?`	`Color.WHITE`	文本颜色
float	`kerning?`	`0`	字符间的额外间距
boolean	`center_x?`	`false`	是否在此位置上水平居中文本
boolean	`center_y?`	`false`	是否在此位置上垂直居中文本
Color	`shadow_color?`	`Color.TRANSPARENT`	文本阴影颜色，透明表示禁用阴影
Vector2D	`shadow_offset?`	`Vector2D(1, 1)`	阴影的偏移量（像素）
boolean	`outlined?`	`false`	是否在文本周围绘制轮廓
Color	`outline_color?`	`Color.BLACK`	轮廓颜色

Moderate

`DrawTexture`

在画布上绘制纹理

此方法只能在 Update 事件内部调用

my_canvas:DrawTexture(texture_path, screen_position, screen_size, coordinate_position, coordinate_size?, render_color?, blend_mode?, rotation?, pivot_point?)

Parameters

Type	Parameter	Default	Description
Image Path	`texture_path`	Required parameter	要绘制的图像
Vector2D	`screen_position`	Required parameter	在画布上的位置（像素）
Vector2D	`screen_size`	Required parameter	在画布上的尺寸（像素）
Vector2D	`coordinate_position`	Required parameter	要绘制源内容的左上角 UV 坐标（0 到 1）
Vector2D	`coordinate_size?`	`Vector2D(1, 1)`	要绘制源内容的 UV 尺寸（0 到 1），使用 (1, 1) 表示整个源内容
Color	`render_color?`	`Color.WHITE`	绘制图形的色调
BlendMode	`blend_mode?`	`BlendMode.AlphaBlend`	推荐为具有透明度的纹理使用 AlphaBlend。否则你可以使用 Opaque。
float	`rotation?`	`0`	旋转（度）
Vector2D	`pivot_point?`	`Vector2D(0.5, 0.5)`	旋转轴心点，相对于绘制尺寸（0.5, 0.5 为中心）

Optimal

`GetSize`

获取画布大小

local size = my_canvas:GetSize()

Returns

Type	Description
Vector2D	当前大小

Moderate

`Repaint`

强制重绘，这将触发 Update 事件

my_canvas:Repaint()

Moderate

`Resize`

如果不使用 auto_resize，调整画布大小

my_canvas:Resize(width, height)

Parameters

Type	Parameter	Default	Description
integer	`width`	Required parameter	宽度（像素）
integer	`height`	Required parameter	高度（像素）

Optimal

`SetAutoRepaintRate`

将其设为 -1 以停止自动重绘，或设为 0 以在每一帧都进行重绘

my_canvas:SetAutoRepaintRate(auto_repaint_rate)

Parameters

Type	Parameter	Default	Description
float	`auto_repaint_rate`	Required parameter	重绘间隔秒数，0 表示逐帧重绘，-1 表示停止自动重绘

Optimal

`SetAutoResize`

设置画布是否应根据屏幕大小自动调整尺寸

my_canvas:SetAutoResize(auto_resize)

Parameters

Type	Parameter	Default	Description
boolean	`auto_resize`	Required parameter	画布是否自动调整尺寸以匹配屏幕大小

Optimal

`SetScreenPosition`

设置画布屏幕位置的偏移量

my_canvas:SetScreenPosition(screen_position)

Parameters

Type	Parameter	Default	Description
Vector2D	`screen_position`	Required parameter	新的画布屏幕位置偏移量

Optimal

`SetVisibility`

设置其在屏幕上是否可见

my_canvas:SetVisibility(visible)

Parameters

Type	Parameter	Default	Description
boolean	`visible`	Required parameter	是否在屏幕上可见

🚀 事件

Inherited Entity Events

Canvas inherits from Base Entity Class, sharing it's events:
Base Entityscripting-reference/classes/base-classes/entity

	Name	Description
	`ClassRegister`	当使用继承系统注册一个新类时触发
	`Destroy`	当实体被销毁时触发
	`Spawn`	当实体被生成/创建时触发
	`ValueChange`	当实体通过 `:SetValue()` 改变了值时触发

	Name	Description
	`Update`	当画布需要被绘制时调用你只能在此事件内部调用 `:Draw...()` 方法

`Update`

当画布需要被绘制时调用

你只能在此事件内部调用 :Draw...() 方法

Canvas.Subscribe("Update", function(self, width, height)
	-- Update was called
end)

Arguments

Type	Argument	Description
Canvas	`self`	触发该事件的画布
integer	`width`	宽度（像素）
integer	`height`	高度（像素）

🎒 示例​

🛠 构造函数​

Default Constructor​

Parameters

🗿 静态函数​

🦠 函数​

Clear​

Parameters

DrawBox​

Parameters

DrawLine​

Parameters

DrawMaterial​

Parameters

DrawMaterialFromSceneCapture​

Parameters

DrawMaterialFromWebUI​

Parameters

DrawPolygon​

Parameters

DrawRect​

Parameters

DrawText​

Parameters

DrawTexture​

Parameters

GetSize​

Returns

Repaint​

Resize​

Parameters

SetAutoRepaintRate​

Parameters

SetAutoResize​

Parameters

SetScreenPosition​

Parameters

SetVisibility​

Parameters

🚀 事件​

Update​

Arguments

🎒 示例

🛠 构造函数

Default Constructor

🗿 静态函数

🦠 函数

`Clear`

`DrawBox`

`DrawLine`

`DrawMaterial`

`DrawMaterialFromSceneCapture`

`DrawMaterialFromWebUI`

`DrawPolygon`

`DrawRect`

`DrawText`

`DrawTexture`

`GetSize`

`Repaint`

`Resize`

`SetAutoRepaintRate`

`SetAutoResize`

`SetScreenPosition`

`SetVisibility`

🚀 事件

`Update`