共计 6440 个字符，预计需要花费 17 分钟才能阅读完成。

运行时脚本接口

运行时脚本接口为 Construct 中的 JavaScript 代码与引擎交互提供了一种方式。

访问运行时脚本接口

通常，运行时脚本接口通过名称 runtime 来访问。但请注意，它并非全局变量：它只在特定地方传递。

所有事件表中的脚本都将 runtime 接口作为参数传递给它们。更多信息请参阅事件表中的脚本。

在脚本文件中，运行时接口仅传递给 runOnStartup() 方法。除此之外，传递它的责任在于您。更多信息请参阅脚本文件。

运行时事件

以下事件可以使用 addEventListener 方法进行监听。

许多输入事件也会在运行时接口上触发。这样它们就可以在 worker 模式下使用，此时 window 和 document 对象不可用，因此无法监听输入事件。运行时传递事件的副本，因为它们可能必须通过 MessageChannel 发送到 worker。

• " 调整大小 "：当显示尺寸发生变化时触发，例如窗口调整大小时。事件对象具有 cssWidth 和 cssHeight 属性，表示主画布的 CSS 单位大小，以及 deviceWidth 和 deviceHeight 属性，表示主画布的设备单位大小。
• " 打勾 "：每个 tick 都会触发，就在运行布局的事件表之前。使用 runtime.dt 属性访问 delta-time 并以该时间量推进游戏逻辑。
• " 之前 ProjectStart"、" 后项目开始 "：仅在项目的第一个布局开始时触发一次。"beforeprojectstart" 在第一个布局上的 "beforelayoutstart" 之前触发，后者又位于布局启动触发器之前。"afterprojectstart" 在第一个布局上的 "afterlayoutstart" 之后触发，后者又位于布局启动触发器之后。在这两个事件中，第一个布局上的所有实例都已创建并可供修改。
• "beforeanylayoutstart"、"afteranylayoutstart"、"beforeanylayoutend"、"afteranylayoutend"：每当任何布局开始或结束时触发。开始事件在布局启动触发器之前和之后触发，结束事件在布局结束触发器之前和之后触发。事件对象具有 layout 属性，它是正在开始或结束的布局的 ILayout。
• " 键控 "、" 键 "：当键盘上的键被按下和释放时触发。这些传递 KeyboardEvent 的副本。
• " 鼠标下降 "、" 鼠标移动 "、" 鼠标 "、"dblclick"：当接收到鼠标输入时触发。这些传递 MouseEvent 的副本。
• " 轮子 "：当接收到鼠标滚轮输入时触发。这传递 WheelEvent 的副本。
• " 指针 "、" 指针移动 "、" 指针 "、" 指针取消 "：当接收到指针输入时触发。这涵盖了鼠标、笔和触摸输入。这些传递 PointerEvent 的副本。Construct 还为 "mouse" 类型的指针添加了一个 lastButtons 属性，用于之前的按钮状态，这使得检测在此事件中是否按下或释放了不同的鼠标按钮变得更加容易。
• " 设备导向 "、" 设备运动 "：当接收到设备方向或运动传感器输入时触发。这些分别传递 DeviceOrientationEvent 或 DeviceMotionEvent 的副本。
• " 保存 "、" 加载 "：当游戏保存系统保存或加载游戏状态时触发。事件对象的 saveData 属性是在 "save" 事件中要保存的额外 JSON 数据，以及在 "load" 事件中最后保存的数据。这允许将脚本中存储的自定义数据与保存系统集成。请注意，这是序列化为 JSON 的，因此无法直接保存对象引用和复杂类型。
• " 实例创建 "：每当创建任何新实例时触发。事件对象具有一个指向创建的 IInstance（或派生）的 instance 属性。
• " 实例销毁 "：每当销毁任何实例时触发。在此事件之后，对该实例的所有引用现在都无效，因此应在此事件中删除或清除对此实例的所有剩余引用。访问销毁后的实例将引发异常或返回无效数据。事件对象具有一个指向被销毁的 IInstance（或派生）的 instance 属性。它还具有一个 isEndingLayout 属性，表示对象是因为布局结束而被销毁还是因其他原因被销毁。
  

  运行时 API

  addEventListener（eventName，回调）
  removeEventListener（eventName，回调）
  添加或删除事件的回调函数。有关可用事件，请参阅上面的运行时事件。
  请参阅处理多个事件示例，了解方便地处理事件的方法。

  对象

  一个对象，该对象具有项目中每个对象类的属性。例如，如果项目有一个名为 Sprite 的对象，则将引用 Sprite 的 IObjectClass 接口。runtime.objects.Sprite
  在某些情况下，对象的名称可能不是有效的 JavaScript 标识符。在这种情况下，您可以使用字符串属性语法，例如 .runtime.objects["Sprite"]
  getInstanceByUid（uid）
  通过实例的 UID（唯一 ID）获取实例（IInstance 或衍生物），UID 是分配给每个实例的唯一编号，可通过其属性访问。uid
  globalVars
  一个对象，该对象具有项目中事件表上每个全局变量的属性。例如，如果项目在名为 Score 的事件表上有全局变量，则提供从脚本访问全局变量的权限。runtime.globalVars.Score
  在某些情况下，事件变量的名称可能不是有效的 JavaScript 标识符。在这种情况下，您可以使用字符串属性语法，例如 .runtime.globalVars["Score"]

  鼠

  对鼠标脚本接口的简写引用。仅当将鼠标插件添加到项目中时，才会设置此设置。

  键盘

  对键盘脚本接口的简写引用。仅当键盘插件添加到项目中时，才会设置此设置。

  触摸

  对 Touch 脚本界面的简写引用。仅当 Touch 插件添加到项目中时，才会设置此设置。

  时间轴控制器

  对 Timeline Controller 脚本接口的简写引用。仅当将 Timeline Controller 插件添加到项目中时，才会设置此设置。

  平台信息

  对 Platform Info 脚本界面的简写引用。仅当将 Platform Info 插件添加到项目中时，才会设置此设置。

  碰撞

  ICollisionEngine 接口提供对冲突 API 的访问。

  布局

  表示当前布局的 ILayout 接口。
  getLayout（layoutNameOrIndex）
  获取项目中布局的 ILayout 接口，通过其名称的不区分大小写的字符串或项目中的从零开始的索引。
  getAllLayouts（）
  返回一个 ILayout 接口数组，这些接口表示项目中的所有布局，并按它们在项目栏中显示的顺序排列。
  goToLayout（layoutNameOrIndex）
  结束当前布局并切换到由其名称的不区分大小写的字符串或项目中从零开始的索引（即布局在项目栏中显示的顺序，所有文件夹都展开）给出的新布局。请注意，在当前报价结束之前不会发生布局切换。

  资产

  一个 IAssetManager 接口，提供对项目资产（如声音和音乐文件或其他项目文件）以及音频解码实用程序的访问。

  存储

  一个 IStorage 接口，提供从脚本访问存储的接口。存储与本地存储插件共享。

  项目名称

  项目名称的字符串，在“项目属性”中指定。

  项目版本

  项目版本的字符串，在“项目属性”中指定。

  视口宽度

  viewport 高度
  getViewportSize（）
  具有项目视口大小的只读数字，如“项目属性”中指定。该方法同时返回两个值。

  采样

  一个只读字符串，指示项目的 Sampling 属性，其中包含其中一个字符串，或。"nearest""bilinear""trilinear"
  isPixelRounding 已启用
  指示项目的像素舍入设置的只读布尔值。

  游戏时间

  以秒为单位返回游戏内时间，该时间受时间刻度的影响。这等价于时间系统表达式。
  wallTime
  以秒为单位返回游戏内时间，不受时间刻度的影响。
  请注意，这并不完全等同于 wallclocktime 系统表达式，因为它只测量游戏中经过的时间，而不是自项目开始以来的时间。

  时间表

  设置或获取一个数字，用于确定项目中时间流逝的速率，例如，1.0 表示正常速度，2.0 表示两倍的速度，等等。这对于慢动作效果或暂停很有用。

  DT 型

  返回 delta-time 的值，即自上一帧以来的时间，以秒为单位。

  dtRaw 的

  返回自上一帧以来的挂钟时间（以秒为单位）。与 dt 不同，“原始”值不受游戏时间刻度或最小 / 最大增量时间钳位的影响。

  最大 Dt

  设置增量时间（）测量的限制。如果实际增量时间增加到最大增量时间以上，则停止增加 Construct 使用的测量值，对应于帧速率下降导致项目以慢动作运行。相反，如果实际增量时间低于最小增量时间，则 Construct 使用的测量值将停止减少，这与帧速率的增加相对应，从而导致项目快进运行。默认值为最小增量时间为 0（表示项目永远不会进入快进模式）和最大增量时间为 1 / 30（对应于 30 FPS 的帧速率），这意味着当帧速率降至 30 FPS 以下时，项目开始进入慢动作。进入快进模式对于“追赶时间”模式很有用，而进入低帧率的慢动作模式有助于防止对象每帧都走得太远，这可能导致跳过碰撞和不稳定的游戏玩法。dt
  请注意帧速率与增量时间之间的反比关系：帧速率越高，增量时间越小，帧速率越低，增量时间越长。

  帧率模式

  在运行时更改项目 Framerate mode 属性。这可以是以下字符串之一：或。有关详细信息，请参阅相应的项目属性。"vsync""unlimited-tick""unlimited-frame"

  帧每秒

  一个只读数字，指示项目呈现的每秒帧数（FPS）。最常见的显示刷新率为 60 Hz，因此通常设计高效的项目将以 60 FPS 的速度呈现。但是请注意，如果屏幕上没有任何变化，则不会呈现任何内容，因此 FPS 测量值可能会降至 0 或显示较低的结果; 这并不表示性能不佳，只是表示渲染所需的帧数较少。该属性指示引擎步进的频率，这可能与每秒渲染的帧数不同。ticksPerSecond

  ticksPerSecond

  一个只读数字，指示项目运行的每秒刻度（TPS）数。每个刻度都处理游戏的逻辑。通常，每个刻度也会渲染一个新帧，但如果没有任何变化，则跳过渲染帧; 此外，根据帧速率模式的不同，步进引擎和绘图帧可能会以不同的速率发生。因此，每秒的刻度可能会产生与每秒帧数不同的测量值。通常，即使视觉上没有任何变化，项目也会不断滴答作响，并且只有在项目暂停时才会停止滴答声，例如最小化或进入后台。

  cpu 利用率

  基于计时器的 Construct 主线程 CPU 使用率在过去一秒内的估计值，以 0-1 范围内的百分比表示。这有助于进行性能测量。但请注意，这仅测量 Construct 知道的函数调用中的时间，因此它可能不包括运行自定义 JavaScript 代码所花费的时间。基于定时器的测量也可能不可靠，因为大多数现代 CPU 在未满载时会故意减慢速度以节省功耗，因此除非系统处于满载状态，否则读数可能会令人误解。

  gpu 利用率

  基于计时器的过去一秒 GPU 使用率估计值，以 0-1 范围内的百分比表示。并非所有设备都支持此功能，在这种情况下，这将返回。基于计时器的测量也可能不可靠，因为大多数现代 GPU 在未满载时会故意减慢速度以节省功耗，因此除非系统处于满载状态，否则读数可能会令人误解。NaN

  callFunction（名称，… 参数）

  通过事件表中的函数名称的不区分大小写的字符串调用函数。在名称之后添加的每个参数都传递给函数。必须至少提供与函数使用的参数一样多的参数，但任何其他参数都将被忽略。如果函数具有返回值，则将从此方法返回该函数，否则返回。null

  setReturnValue（值）

  这只能从返回类型不是 None 的事件表函数中的脚本调用。它实质上等同于“设置返回值”操作。但是，可以从脚本调用此方法这一事实可以更轻松地从事件表函数的脚本返回值。例如，事件表函数可以包含带有代码的单个脚本操作，这意味着无论在哪里调用事件表函数，它都会返回 JavaScript 中调用的值。runtime.setReturnValue(getMyValue())getMyValue()

  随机（）

  返回 [0，1] 范围内的随机数。这与 类似，但如果 Advanced Random 对象覆盖系统随机值，则可以生成确定性值序列。Math.random()

  sortZOrder（可迭代，回调）

  使用自定义排序函数作为回调，对可迭代对象给出的所有 IWorldInstances 的相对 Z 顺序进行排序，该回调接收两个 IWorldInstance 作为参数进行比较。下面给出了一个使用 myZOrder 实例变量对 Sprite 对象的实例进行排序的示例。
  

invokeDownload（url，文件名）

在给定的 url 处调用资源的下载，使用给定的文件名进行下载。可以使用此方法下载本地生成的内容，方法是使用 url 的数据 URI 或 blob URL。

isInWorker

一个只读布尔值，指示运行时当前是否在 Web 辅助角色的上下文中运行。这由 Use worker 项目属性控制。在工作线程模式下，可以使用一组更有限的浏览器 API。请参见可供 Web Worker 使用的函数和类。

异步 createWorker（url，opts）

一种帮助程序方法，用于在运行时本身位于辅助角色中时创建 Web 辅助角色。脚本 URL 和选项的参数与传递给 Worker（）构造函数的参数相同; 但是，此方法是异步的，并使用 MessagePort 进行解析，以便与工作线程通信。有关更多详细信息和代码示例，请参阅创建 Web 辅助角色指南。

getHTMLLayer（索引）

检索用于包含项目中给定 HTML 层上的所有 HTML 内容的 HTML 元素。索引是 HTML 层（而不是 Construct 层）的从零开始的索引。此方法只能在 DOM 模式下使用 – 如果项目属性 Use worker 为 Yes，则调用此方法将引发异常。此方法可用于获取用于插入自定义 HTML 内容的父元素，以便根据 Construct 的 HTML 层之一显示分层。有关详细信息，请参阅 HTML 图层。

异步警报（消息）

使用 alert（）方法显示警报消息提示。这是作为运行时方法提供的，因为它在工作器模式下将调用转发到 DOM。请注意，与标准浏览器方法不同，这是一种异步方法 – 在工作线程模式下，它返回一个承诺，该承诺在警报关闭时解析，并且在显示警报时，工作线程中的执行将继续。在 DOM 模式下，警报处于阻塞状态，并将在警报显示时停止所有执行（但它仍返回一个承诺，该承诺在警报关闭时解析）。alert()
此方法还可用作工作器模式下的全局函数。这是为了帮助确保简单的测试代码按预期工作，即使代码无意中在 Web Worker 的上下文中运行，其中浏览器方法通常不可用。alert()alert()

运行时 SDK 事件和 API

这些事件和 API 通常只用于 Addon SDK，在 Construct 中使用 JavaScript 编码时通常不应使用。但是，由于它们也是界面的一部分，因此此处也记录了它们。IRuntime

SDK 事件

“后载”
在其余运行时完成加载某些已保存状态后触发调用。这意味着所有对象都可用，并且可以通过其 UID 进行查找。例如，要保存对实例的引用，请将其 UID 保存为 JSON，加载其 UID 并将其存储在 中，然后在“afterload”事件中查找它。_loadFromJson()_loadFromJson()getInstanceByUid()

SDK API

addLoadPromise（承诺）
仅在项目仍在加载时有效。添加一个承诺，即运行时在启动第一个布局之前将等待解析。如果你想确保你的插件在项目开始之前加载动态资源，或者从 DOM 或包装器扩展获得响应，这将非常有用。
单全局插件在加载之前创建其实例，因此此方法可以在单全局实例构造函数中使用。否则，它只能在插件或行为构造函数中使用。[/ti]