API 参考

完整 API 参考

也可以在编辑器内部以简短形式获得：

资产构造函数

构造函数创建编辑器使用的主要资产类型。当您将一个分配给变量时，编辑器会识别它并允许您使用 Ctrl+Click 打开匹配的资产编辑器。

函数	描述
`Sprite(width, height)`	创建具有指定尺寸的精灵资产
`Scene()` 或 `Scene(name)`	创建场景资产
`Audio()`	创建一个微型的追踪风格音频资产
`Object()` 或 `Object(name)`	创建游戏对象

列表方法

使用 [] 或 [value1, value2, ...] 创建列表。使用 list[index] 读取和覆盖条目，并用 for (var i = 0; i < list.length(); i = i + 1) 进行迭代。

函数	描述
`list.add(value)`	将值追加到列表末尾
`list.length()`	返回列表中的元素数量
`list.remove(index)`	移除给定索引处的元素
`list.clear()`	移除列表中的所有元素

运算符

运算符是执行常见计算的小符号。模运算符对于包装计时器、索引、动画步骤或重复模式特别有用。

运算符	描述
`%`	模运算。返回除法后的余数

对象属性

对象是您的脚本通常在游戏中移动和更改的东西。这些函数读取或更新对象的位置、精灵、碰撞行为、图层和视觉色调。

函数	描述
`getX(obj)`	返回对象的 X 位置
`setX(obj, x)`	设置对象的 X 位置
`getY(obj)`	返回对象的 Y 位置
`setY(obj, y)`	设置对象的 Y 位置
`getVelocityX(obj)`	返回对象的 X 速度
`setVelocityX(obj, vx)`	设置对象的 X 速度
`getVelocityY(obj)`	返回对象的 Y 速度
`setVelocityY(obj, vy)`	设置对象的 Y 速度
`getName(obj)`	返回对象的名称
`setName(obj, name)`	设置对象的名称
`getSprite(obj)`	返回对象的精灵
`setSprite(obj, sprite)`	将精灵分配给对象（重置动画为帧 0）
`getLayer(obj)`	返回对象的绘制层
`setLayer(obj, layer)`	设置对象的绘制层（层级越高 = 绘制越晚）
`getTint(obj)`	返回色调作为 [r, g, b, a] 列表
`setTint(obj, r, g, b, a)`	设置对象的颜色色调（每个值为 0-255）
`getCollisionType(obj)`	返回碰撞类型编号
`setCollisionType(obj, type)`	设置碰撞类型

精灵函数

精灵函数允许代码检查或修改精灵像素数据和动画速度。大多数游戏在编辑器中绘制精灵，但这些函数对于程序效果、调试或简单的运行时更改非常有用。

函数	描述
`fillSprite(sprite, r, g, b, a)`	用纯 RGBA 颜色（0-255）填充所有帧的所有像素
`getPixel(sprite, frame, x, y)`	返回给定帧中 (x,y) 处像素的 [r,g,b,a]，如果超出边界则返回 null
`setPixel(sprite, frame, x, y, r, g, b, a)`	设置给定帧中 (x,y) 处像素的颜色。如果超出边界则不做任何事
`getAnimationFPS(sprite)`	返回精灵的动画速度（每秒帧数）
`setAnimationFPS(sprite, fps)`	设置精灵的动画速度（每秒帧数）

动画函数

动画函数针对使用多个帧的精灵的对象。当你想让代码检查或强制当前动画帧时使用它们。

函数	描述
`getFrame(obj)`	返回对象的当前动画帧索引
`setFrame(obj, frameIndex)`	设置对象的动画帧（重置计时器）
`getFrameCount(obj)`	返回对象精灵中的帧数

变换函数（翻转/旋转）

变换函数改变对象的精灵如何绘制，而不编辑精灵本身。它们适合于在多个方向上重用一个精灵。

函数	描述
`getFlipX(obj)`	返回对象是否水平翻转
`setFlipX(obj, flip)`	设置水平翻转。`true` = 翻转，`false` = 正常
`getFlipY(obj)`	返回对象是否垂直翻转
`setFlipY(obj, flip)`	设置垂直翻转。`true` = 翻转，`false` = 正常
`getRotation(obj)`	返回对象的顺时针旋转角度（度数）
`setRotation(obj, degrees)`	设置对象的顺时针旋转角度（度数）
`move(obj, x, y)`	在其局部旋转轴上移动对象。正 X 向右移动，正 Y 向下移动
`getCenterOffset(obj)`	返回标准化的旋转枢轴，格式为 `[x, y]`
`setCenterOffset(obj, x, y)`	设置标准化的旋转枢轴。值限制在 `0` 到 `1` 之间
`getCenterOffsetX(obj)`	返回标准化的枢轴 X
`setCenterOffsetX(obj, x)`	设置标准化的枢轴 X
`getCenterOffsetY(obj)`	返回标准化的枢轴 Y
`setCenterOffsetY(obj, y)`	设置标准化的枢轴 Y
`getCenter(obj)`	返回旋转枢轴的世界位置，格式为 `[x, y]`
`setCenter(obj, x, y)`	将对象移动到其旋转枢轴处于世界位置 `(x, y)`
`getCenterX(obj)`	返回旋转枢轴的世界 X 位置
`setCenterX(obj, x)`	将对象移动到其枢轴在世界 X 上的值 `x`
`getCenterY(obj)`	返回旋转枢轴的世界 Y 位置
`setCenterY(obj, y)`	将对象移动到其枢轴在世界 Y 上的值 `y`
`getDirectionRight(obj)`	返回对象的旋转右方向，格式为 `[x, y]`
`getDirectionDown(obj)`	返回对象的旋转下方向，格式为 `[x, y]`
`getDirectionLeft(obj)`	返回对象的旋转左方向，格式为 `[x, y]`
`getDirectionUp(obj)`	返回对象的旋转上方向，格式为 `[x, y]`

默认中心偏移为 [0.5, 0.5]，表示围绕精灵的中间旋转。[0, 0] 围绕对象的左上角旋转，而 [1, 1] 则围绕 位置 + (宽度, 高度) 旋转。

对于旧项目的警告： 从 Tiniest2D 1.8 开始，getRotation() 和 setRotation() 使用度数角，而不是四分之一转值。旋转对象的碰撞器现在会影响物理和场景查询。

碰撞类型

碰撞类型决定对象如何参与碰撞检查。根据对象的角色选择类型：墙壁通常是静态的，玩家通常是动态的，而捡起物品往往是触发器。

常量	值	描述
`COLLISION_NONE()`	0	无碰撞检测
`COLLISION_STATIC()`	1	碰撞但不移动
`COLLISION_DYNAMIC()`	2	碰撞并被推出
`COLLISION_TRIGGER()`	3	检测碰撞但不阻止

场景函数

场景函数控制哪个场景处于活动状态，哪些对象在其中，以及场景范围设置，如背景颜色和重力。它们还提供搜索助手，以查找特定位置或名称的对象。

函数	描述
`addObject(scene, obj)`	将对象添加到场景中
`removeObject(scene, obj)`	从场景中移除对象
`setScene(scene)`	设置活动场景
`getScene()`	返回当前活动场景
`resetScene(scene)`	将场景重置为其初始状态（如在编辑器中设计的）
`setBackgroundColor(scene, r, g, b)`	设置场景背景颜色（RGB 0-255）
`getBackgroundColor(scene)`	返回背景颜色作为 [r, g, b] 列表
`getGravityX(scene)`	返回场景重力的 X 分量
`setGravityX(scene, gx)`	设置场景重力的 X 分量
`getGravityY(scene)`	返回场景重力的 Y 分量
`setGravityY(scene, gy)`	设置场景重力的 Y 分量（正值 = 向下）
`getObjectAt(scene, x, y)`	返回 (x,y) 点上的第一个对象，或者返回 null
`getObjectsAt(scene, x, y)`	返回 (x,y) 点上的所有对象的列表
`getObjectsInBox(scene, x, y, w, h)`	返回所有重叠盒子的对象
`getObjectByName(scene, name)`	按名称查找对象，如果未找到则返回 null
`getObjectCount(scene)`	返回场景中的对象数量
`getAllObjects(scene)`	返回场景中所有对象的列表
`isObjectInScene(scene, obj)`	如果对象在场景中返回 true
`getObjectsBySprite(scene, sprite)`	返回所有使用给定精灵的对象
`getObjectsByCollisionType(scene, type)`	返回具有给定碰撞类型的所有对象

音频播放

音频播放函数从脚本中开始和停止音频资产。playAudio() 返回一个句柄，以便您之后可以停止或检查特定的播放实例。

函数	描述
`playAudio(audio)`	启动音频资产并返回播放句柄 ID
`stopAudio(handle)`	停止 `playAudio()` 返回的播放句柄
`isAudioPlaying(handle)`	当播放句柄仍处于活动状态时返回 true

屏幕函数

屏幕函数在您需要知道窗口大小或进行屏幕像素和世界位置之间的转换时提供帮助。这在鼠标瞄准、点击检测和相机感知用户界面中非常有用。

函数	描述
`getScreenWidth()`	返回屏幕/窗口的宽度（以像素为单位）
`getScreenHeight()`	返回屏幕/窗口的高度（以像素为单位）
`screenToWorld(screenX, screenY)`	将屏幕像素坐标转换为世界坐标。返回 [worldX, worldY]
`worldToScreen(worldX, worldY)`	将世界坐标转换为屏幕像素坐标。返回 [screenX, screenY]

窗口模式

控制导出游戏的窗口模式。这些函数在编辑器中播放时无效（编辑器对窗口状态有更高的控制权）。

常量	值	描述
`WINDOW_WINDOWED()`	0	常规窗口模式
`WINDOW_MAXIMIZED()`	1	最大化窗口（默认）
`WINDOW_FULLSCREEN()`	2	无边框全屏

函数	描述
`getWindowMode()`	返回当前窗口模式常量
`setWindowMode(mode)`	设置窗口模式。仅在导出的游戏中有效

示例:

func start() {
    // 设置窗口模式（WINDOW_MAXIMIZED 是导出游戏的默认模式）
    setWindowMode(WINDOW_MAXIMIZED())
}

注意: 如果在导出的游戏中从未调用过 setWindowMode()，默认值为 WINDOW_MAXIMIZED。

UI 函数

UI 使用虚拟屏幕空间分辨率。默认 UI 空间为 100 x 100。字体大小可以通过 uiPushFontSize(size) 为后续文本小部件调整，并通过 uiPopFontSize() 恢复。字体颜色可以通过 uiPushFontColor(r, g, b[, a]) 堆叠，UI 元素填充可以通过 uiPushElementColor(r, g, b[, a]) 堆叠。与其他即时模式 UI 一样，这些重写在构建当前帧的 UI 时有效。如果推送的大小为 0 或更小，引擎将使用自动大小。

函数	描述
`getUIResolutionX()`	返回当前虚拟 UI 宽度
`setUIResolutionX(width)`	设置后续 UI 调用使用的虚拟 UI 宽度
`getUIResolutionY()`	返回当前虚拟 UI 高度
`setUIResolutionY(height)`	设置后续 UI 调用使用的虚拟 UI 高度
`uiPushFontSize(size)`	为后续 UI 文本推送字体大小缩放。值 `<= 0` 使用自动大小
`uiPopFontSize()`	弹出最近的 UI 字体大小重写
`uiPushFontColor(r, g, b)` 或 `uiPushFontColor(r, g, b, a)`	为后续 UI 文本推送字体颜色重写
`uiPopFontColor()`	弹出最近的 UI 字体颜色重写
`uiPushElementColor(r, g, b)` 或 `uiPushElementColor(r, g, b, a)`	为框、按钮、切换、滑块和图像按钮推送填充颜色重写
`uiPopElementColor()`	弹出最近的 UI 元素颜色重写
`uiLabel(text, x, y)`	在虚拟 UI 坐标处绘制屏幕空间文本
`uiBox(x, y, w, h)`	绘制一个简单的面板框
`uiButton(text, x, y, w, h)`	绘制一个按钮并返回 `UI_*()` 状态常量之一
`uiToggle(text, value, x, y, w, h)`	绘制一个切换并返回更新的布尔值
`uiSlider(text, value, min, max, x, y, w, h)`	绘制一个滑块并返回更新的数值
`uiSprite(sprite, x, y)`	在 UI 空间中以 UI 单位的自然大小绘制一个精灵
`uiSprite(sprite, x, y, w, h)`	在 UI 空间中以显式大小绘制一个精灵
`uiImageButton(sprite, x, y, w, h)`	绘制一个精灵按钮并返回 `UI_*()` 状态常量之一

UI 状态常量

UI 函数返回状态常量，以便你的脚本可以判断小部件是处于闲置、悬停、按下还是点击状态。通常 UI_CLICKED() 是你检查按钮操作的值。

常量	值	描述
`UI_IDLE()`	0	小部件既没有悬停也没有按下
`UI_HOVERED()`	1	鼠标悬停在小部件上
`UI_HELD()`	2	鼠标按钮在小部件上被按下
`UI_CLICKED()`	3	本帧小部件被点击

相机函数

相机位置代表视图的中心。缩放保持垂直世界视图的一致性，无论屏幕大小如何。

函数	描述
`getCameraX(scene)`	返回相机 X 位置（视图中心）
`setCameraX(scene, x)`	设置相机 X 位置
`getCameraY(scene)`	返回相机 Y 位置（视图中心）
`setCameraY(scene, y)`	设置相机 Y 位置
`getCameraZoom(scene)`	返回相机缩放级别
`setCameraZoom(scene, zoom)`	设置相机缩放。缩放 1.0 显示 720 个世界单位的垂直视图，3.0 显示 240 个单位。

缩放行为: 缩放保持垂直世界视图的一致性，无论窗口大小或纵横比如何。更宽的屏幕水平显示得更多，但垂直显示的量相同。

输入函数

输入函数让游戏能够响应键盘和鼠标状态。使用 Pressed 进行单帧动作，使用 Held 进行连续移动，使用 Released 进行按钮放开时发生的动作。

函数	描述
`isKeyPressed(key)`	仅在按下键的那一帧为真
`isKeyHeld(key)`	在按住键时为真
`isKeyReleased(key)`	仅在释放键的那一帧为真
`getMouseX()`	返回屏幕坐标中的鼠标 X
`getMouseY()`	返回屏幕坐标中的鼠标 Y
`getMouseDeltaX()`	返回这一帧鼠标 X 的移动
`getMouseDeltaY()`	返回这一帧鼠标 Y 的移动
`isMouseButtonPressed(button)`	仅在按下鼠标按钮的那一帧为真
`isMouseButtonHeld(button)`	在按住鼠标按钮时为真
`isMouseButtonReleased(button)`	仅在释放鼠标按钮的那一帧为真
`getFPS()`	返回当前每秒帧数

鼠标按钮常量

鼠标按钮常量被传递给鼠标输入函数。它们使代码比原始数字更易于阅读。

常量	描述
`MOUSE_LEFT()`	左鼠标按钮
`MOUSE_RIGHT()`	右鼠标按钮
`MOUSE_MIDDLE()`	中间鼠标按钮

键常量

键常量被传递给键盘输入函数。引擎公开字母、数字、功能键、箭头和一小部分常用特殊键。

字母: KEY_A() 至 KEY_Z()

数字: KEY_0() 至 KEY_9()

功能键: KEY_F1() 至 KEY_F12()

特殊键: | 常量 | 键 | |------|-----| | KEY_SPACE() | 空格键 | | KEY_ENTER() | 回车/输入 | | KEY_ESCAPE() | 逃脱 | | KEY_TAB() | Tab | | KEY_BACKSPACE() | 退格 | | KEY_DELETE() | 删除 | | KEY_SHIFT() | Shift | | KEY_CTRL() | 控制 | | KEY_ALT() | Alt | | KEY_LEFT() | 左箭头 | | KEY_RIGHT() | 右箭头 | | KEY_UP() | 上箭头 | | KEY_DOWN() | 下箭头 | | KEY_HOME() | 首页 | | KEY_END() | 结束 |

数学函数

数学助手包含运动、动画、随机性和数值限制中常用的计算。它们使脚本更短且更易于阅读。

函数	描述
`abs(n)`	绝对值
`min(a, b)`	返回两个数中较小值
`max(a, b)`	返回两个数中较大值
`clamp(value, min, max)`	将值限制在最小值和最大值之间
`lerp(a, b, t)`	线性插值从 `a` 到 `b` 使用 `t`
`floor(n)`	向下取整到最近的整数
`ceil(n)`	向上取整到最近的整数
`round(n)`	四舍五入到最近的整数
`sign(n)`	根据输入的符号返回 `-1`、`0` 或 `1`
`sqrt(n)`	平方根
`pow(base, exponent)`	将基数提升到指数
`sin(radians)`	角度的正弦（弧度）
`cos(radians)`	角度的余弦（弧度）
`tan(radians)`	角度的正切（弧度）
`random()`	返回一个介于 0.0 和 1.0 之间的随机浮点数
`randomRange(min, max)`	返回一个介于最小值和最大值之间的随机浮点数
`randomInt(min, max)`	返回一个介于最小值和最大值之间的随机整数（包括边界）
`PI()`	返回圆周率 (3.14159...)
`TAU()`	返回 tau (2 * pi = 6.28318...)
`TWOPI()`	返回 2 * pi (与 TAU 相同)
`E()`	返回欧拉数 e (2.71828...)
`deg2rad(degrees)`	将度转换为弧度
`rad2deg(radians)`	将弧度转换为度

工具函数

工具函数是通用助手，不属于特定资产类型。print() 在学习过程中特别有用，因为它显示你的脚本正在执行的内容。

函数	描述
`print(value)`	打印到调试输出（在游戏中显示）
`quitGame()`	退出游戏。在编辑器中停止播放模式。在导出游戏中关闭应用程序

字符串函数

字符串函数处理文本值。目前这一部分故意很小。

函数	描述
`strlen(string)`	返回字符串的长度（字符数）

存储函数

将游戏数据保存和加载到文件中。支持数字、字符串、布尔值和列表（包括嵌套列表）。不支持精灵、场景、对象或音频值。

函数	描述
`save(path, data)`	将数据以二进制格式保存到文件。成功时返回 `true`
`save(path, data, format)`	使用指定格式保存数据：`"binary"` 或 `"text"`
`save(path, data, format, key)`	使用提供的密钥字符串进行加密保存数据
`load(path)`	从文件加载数据。失败时返回数据或 `null`
`load(path, key)`	使用提供的密钥字符串加载加密数据
`fileExists(path)`	如果在给定路径存在文件，则返回 `true`
`deleteFile(path)`	删除给定路径下的文件。成功时返回 `true`
`getAppDataPath()`	返回 AppData/Tiniest2D 文件夹路径（如有必要则创建）
`getDocumentsPath()`	返回用户的文档文件夹路径
`getGamePath()`	返回游戏可执行文件所在的目录

示例：保存和加载玩家进度

// 保存玩家数据
var playerData = [100, "Player1", true, [1, 2, 3]]
var savePath = getAppDataPath() + "/MyGame/save.dat"
if (save(savePath, playerData)) {
    print("游戏已保存！")
}

// 加载玩家数据
if (fileExists(savePath)) {
    var loaded = load(savePath)
    if (loaded != null) {
        var health = loaded[0]
        var name = loaded[1]
        var hasKey = loaded[2]
        var inventory = loaded[3]
    }
}

// 加密保存（用于隐藏数据以防随意检查）
var secretData = ["secret", 12345]
save(getAppDataPath() + "/MyGame/config.dat", secretData, "binary", "mySecretKey")
var decrypted = load(getAppDataPath() + "/MyGame/config.dat", "mySecretKey")

// 文本格式（可人读，适合调试）
save(getAppDataPath() + "/MyGame/debug.txt", playerData, "text")

注意事项：

二进制格式（默认）紧凑且更快
文本格式可人读，适合于调试
错误的加密密钥返回 null（数据将无效）
保存时目录会自动创建

使用 Tiniest2D 制作 2D 游戏

引擎 API 参考

Keep your place in this quest