系统 API

系统 API 通过 executePluginCommand('system', ...) 调用，提供窗口管理、截图和应用控制等能力。

窗口管理

setWindowSize — 设置窗口大小

executePluginCommand('system', {
  subCommand: 'setWindowSize',
  width: 1920,
  height: 1080,
  factor: 1.0,          // 可选：缩放因子
});

参数	类型	说明
`width`	`number`	窗口宽度（像素）
`height`	`number`	窗口高度（像素）
`factor`	`number`	可选，缩放因子（DPI 缩放）

setWindowState — 设置窗口状态

executePluginCommand('system', {
  subCommand: 'setWindowState',
  state: 'fullscreen',   // 'maximized' | 'minimized' | 'fullscreen' | 'normal'
});

getWindowState — 获取窗口状态

const state = executePluginCommand('system', {
  subCommand: 'getWindowState',
});
// 返回 'maximized' | 'minimized' | 'fullscreen' | 'normal'

setTitle — 设置窗口标题

executePluginCommand('system', {
  subCommand: 'setTitle',
  title: '末语 — 第一章',
});

getWindowInnerPosition — 获取窗口内部位置

返回窗口内容区域左上角相对于屏幕的坐标。

const pos = executePluginCommand('system', {
  subCommand: 'getWindowInnerPosition',
});
// 返回 { x: number, y: number }

getWindowInnerSize — 获取窗口内部尺寸

返回窗口内容区域的实际像素尺寸。

const size = executePluginCommand('system', {
  subCommand: 'getWindowInnerSize',
});
// 返回 { width: number, height: number }

舞台

getStageSize — 获取舞台尺寸

返回引擎渲染区域的逻辑尺寸（与 index.json 中的配置对应）。

const size = executePluginCommand('system', {
  subCommand: 'getStageSize',
});
// 返回 { width: number, height: number }

getPlatform — 获取运行平台

同步返回引擎构建目标对应的平台标记。所有字段均在编译期确定，可用于按平台选择功能或资源。

import { getPlatform } from '@momoyu-ink/kit';

const platform = getPlatform();

if (platform.isAndroid || platform.isIOS) {
  // Use touch controls.
}

也可以直接调用 system plugin：

const platform = executePluginCommand('system', {
  subCommand: 'getPlatform',
});

字段	类型	说明
`isLinux`	`boolean`	是否为 Linux
`isMacOS`	`boolean`	是否为 macOS
`isAndroid`	`boolean`	是否为 Android
`isIOS`	`boolean`	是否为 iOS
`isWasm`	`boolean`	是否为 WebAssembly 构建，与 `isWeb` 等价
`isNative`	`boolean`	是否为原生平台（即所有非 Web 平台）构建
`isDesktop`	`boolean`	是否为桌面平台（即 Windows、macOS 或 Linux）构建
`isMobile`	`boolean`	是否为移动平台（即 Android 或 iOS）构建
`isWeb`	`boolean`	是否为 Web 构建

截图

takeSnapshot — 截取当前画面

截取当前渲染帧的画面。截图会存储在引擎内部，可用于存档等用途。

executePluginCommand('system', {
  subCommand: 'takeSnapshot',
  width: 640,             // 可选：缩放宽度
  height: 360,            // 可选：缩放高度
  keepAspectRatio: true,  // 可选：保持宽高比
});

参数	类型	说明
`width`	`number`	可选，截图宽度
`height`	`number`	可选，截图高度
`keepAspectRatio`	`boolean`	可选，是否保持宽高比

文件读取

readFile — 读取文件

读取指定路径的文件内容，以 Promise<string | ArrayBuffer> 形式返回。路径使用 URL 格式，仅允许以下三种 scheme：

scheme	对应目录
`assets:`	游戏资源目录（`assets/`）
`saves:`	存档目录
`data:`	应用数据目录

const text = await executePluginCommand('system', {
  subCommand: 'readFile',
  path: 'assets:///data/config.json',
  format: 'text',   // 可选，默认 'text'
});

参数	类型	说明
`path`	`string`	文件 URL，格式为 `scheme:///path/to/file`
`format`	`'text' \| 'binary'`	可选，文件格式，默认 `'text'`

应用控制

openUrl — 在默认浏览器中打开链接

在系统默认浏览器中打开 HTTP 或 HTTPS 链接。

executePluginCommand('system', {
  subCommand: 'openUrl',
  url: 'https://momoyu.ink/',
});

参数	类型	说明
`url`	`string`	要打开的 HTTP 或 HTTPS URL

getParams — 获取自定义参数

const params = executePluginCommand('system', {
  subCommand: 'getParams',
});

quit — 退出应用

executePluginCommand('system', {
  subCommand: 'quit',
});