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)`	返回对象的 90 度旋转（0-3）
`setRotation(obj, rot)`	设置 90 度旋转：0=0，1=90，2=180，3=顺时针 270 度

注意： 这些变换仅在渲染时应用。它们不影响碰撞盒或实际精灵像素数据。

碰撞类型

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

常量	值	描述
`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

屏幕函数

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

函数	描述
`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() | Esc | | 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() | Home | | KEY_END() | End |

数学函数

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

函数	描述
`abs(n)`	绝对值
`min(a, b)`	返回两个数字中较小的一个
`max(a, b)`	返回两个数字中较大的一个
`clamp(value, min, max)`	将值夹在最小值和最大值之间
`lerp(a, b, t)`	使用 `t` 从 `a` 线性插值到 `b`
`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()`	返回 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