FlexCore 初始化、迁移、引擎升级与完整运行操作手册
适用于 FlexCore Engine 1.0.0,当前交付为 2026-10-28 的 r2 修订。本文修订于 2026-10-28。下载与版本记录;已有项目更新程序请先看升级指南。
先了解要使用什么
| 内容 | 用途 |
|---|---|
| Windows 开发包 | 包含编辑器、Server、开发工具、SDK、配套编译器与 Windows/Android 导出模板。用于制作游戏。 |
| Linux 部署包 | 运行已有 Server/Auth;不提供 Linux 编辑器。 |
| Server | 游戏服务器,执行游戏逻辑,使用 server.toml。 |
| Auth | 可选的玩家登录认证服务,使用 auth.toml,需要 MySQL 和 Redis。它与论坛引擎授权分别处理。 |
| 导出模板 | 游戏客户端的运行程序壳,配合项目内容生成玩家使用的成品。 |
Server/Auth/Tools 为 1.0.0+build.1,编辑器和模板为 1.0.0+build.540,客户端 SDK 为 1.3.0,服务端 SDK 为 1.1.0-rc.0。Auth 服务和 Auth SDK 为候选组件,工具及内容 SDK 为预览组件,正式使用前按自身场景确认。
Windows 开发包已配套 Node.js、npm、TypeScript,无需引擎源码或全局安装这些开发工具。Android 导出另需 Android SDK、JDK 和应用签名配置。发行清单带签名;Windows 程序没有系统代码签名。
下面的 Windows 命令均在解压后的开发包根目录打开 PowerShell 执行。..\我的游戏 等为示例目录,可按自己的位置替换。每条命令执行后检查 $LASTEXITCODE;非 0 时先处理对应错误,不继续当作成功。Linux 示例使用终端命令及 / 路径分隔符。
下载后先检查
从版本记录下载适合平台的程序包和同名 .sha256 文件。完整合规材料单独提供;程序包保留必要第三方许可,请勿擅自移除。将程序包解压到自己选择的位置,保留原始压缩包。
先核对压缩包 SHA-256,再使用从官方可信渠道独立确认的验证公钥检查解压目录。具体命令及成功判据见下载、解压和检查。这些检查用于确认发行文件,与日常程序领取使用授权分别处理。
新建游戏项目
没有现有项目时执行:
.\tools\fc-tools.exe game init --project '..\我的游戏' --engine-root . --name '我的游戏'
出现 游戏开发目录已初始化 且退出码为 0 表示初始化成功。生成目录包含客户端工程文件和服务的配置文件,服务端 SDK 由交付包离线恢复。按生成的 README 继续填写本项目所需配置;初始化成功不代表数据库、通信证书或授权已经可用。
打开客户端工程:
.\client\flexcore-editor.exe --path '..\我的游戏\editor'
已有项目直接打开相应的客户端工程文件,无需另建项目。首次需要引擎授权时按下一节确认;已有有效材料时直接继续。
只需要独立服务端项目时,可改用:
.\tools\fc-tools.exe server init --project '..\服务端项目' --install --engine-root .
.\tools\fc-tools.exe server check --project '..\服务端项目'
.\tools\fc-tools.exe server build --project '..\服务端项目'
第一条生成模板并离线恢复交付 SDK;后两条分别检查项目和编译脚本,每项退出码应为 0。现有项目也可用第一条补齐并恢复依赖,保留已有配置。不带 --install 只生成项目,普通 npm install 不保证取得本次随包的预发布 SDK。
首次启动如何取得引擎授权
引擎授权用于开发者使用编辑器和游戏服务器,与玩家进入游戏的账号分别处理。论坛官方地址已有默认值,无需在配置中重复填写。可用用途和截止时间以论坛为该账号实际开通的权益为准,编辑器权益与服务器权益不能互换。
Windows 正常打开编辑器或交互启动 Server 时,程序先检查本地授权;材料有效便继续。需要本人确认时会尝试打开论坛页面,登录论坛账号并确认所申请的用途;浏览器没有自动打开时,使用窗口或终端提供的链接。保持原程序打开,确认后等待其领取、验签、保存并继续启动。
Linux 在终端显示确认链接和用户码,可用手机或另一台电脑的浏览器确认;其余登录、领取和刷新流程与 Windows 一致。论坛会提示没有权益、权益过期或暂停等情况;确认身份本身不会自动开通权益。多项可用权益时按页面提示选择。
程序会在正常有效期结束前尝试自动刷新,短期断网可继续使用仍在允许范围内的材料。站点默认正常有效期为 24 小时,总离线截止为签发后 72 小时,72 小时已经包含前面的 24 小时;两者均不能超过账号权益截止时间。管理员可调整后续签发策略,实际期限以材料为准。这不表示每天需要购买或重新登录。账号会话失效时按提示重新确认,不删除验证状态或关闭验签。
授权文件和配置放在哪里
| 对象 | 默认位置与说明 |
|---|---|
| Server 配置 | 不传 --config 时读取程序旁的 server.toml;可显式选择其他文件。 |
| Server 授权材料 | [license].cache_file 默认为配置旁的 license-cache.json,保留其中的已有验证状态。 |
| Linux 账号会话 | [license].session_file 默认为配置旁的 license-session.json;含敏感凭据,不公开、不随玩家包分发。 |
| Windows 账号会话 | 使用系统原生凭据存储;不会通过复制 Linux 会话文件迁移 Windows 登录。 |
| 编辑器授权配置 | editor-license.json 放在编辑器现有配置目录;Windows 默认 %APPDATA%\flexcore,便携模式沿用已有 editor_data。 |
编辑器可以用 --editor-license-config <配置文件> 指定配置。Server 和编辑器配置中的相对材料路径均按所选配置文件所在目录解析;命令行相对路径则按命令执行位置解析。不增加授权专用目录,也不要求固定盘符。移动配置时检查相对路径仍指向实际材料。
Windows 取得的完整 Core 服务器授权缓存可以复制到 Linux,保留已有验证状态,并在目标程序执行授权状态检查。复制不延长期限,不迁移 Windows 登录会话;Linux 需要自动在线刷新时仍应完成一次论坛确认。编辑器缓存不能代替服务器缓存。配置和凭据不要放入游戏客户端或公开资源目录。
Server 手动登录、领取和检查
正常交互启动优先使用前述自动流程。部署为后台服务或需要单独排查授权时,在与实际运行相同的配置、账号环境中先完成以下操作。Windows 示例:
$server = '.\server\flexcore-server.exe'
$config = '..\我的游戏\server\server.toml'
& $server license login --config $config
& $server license claim --config $config --entitlement '<服务器权益编号>'
& $server license status --config $config
第一条按输出到论坛确认;第二条把 <服务器权益编号> 替换成该账号的实际服务器权益编号;第三条检查材料有效性、用途和期限。各项退出码应为 0,状态检查确认用途与本次 Server 相符后再启动。
后续手动刷新:
& $server license refresh --config $config
& $server license status --config $config
刷新不需要再填权益编号。Linux 在部署包根目录使用 ./server/flexcore-server license login --config ../my-game/server/server.toml,其他子命令及参数相同。后台非交互服务不会等待网页登录,请先在交互终端完成配置和材料准备,再确保服务进程实际能读写所选文件。
编辑器的无界面操作、自动化和导出不会等待网页。用同一配置分别执行 --editor-license-login、--editor-license-claim、--editor-license-status 完成准备;权益不唯一时按提示在配置选择编号。普通桌面启动仍可直接按界面确认。
运行游戏服务器
先检查并编译项目,再按实际配置启动。Windows 示例:
.\tools\fc-tools.exe server check --project '..\我的游戏\server'
.\tools\fc-tools.exe server build --project '..\我的游戏\server'
.\server\flexcore-server.exe --config '..\我的游戏\server\server.toml'
Linux 使用对应 Linux 程序与项目配置:
./server/flexcore-server --config ../my-game/server/server.toml
日志出现 网络服务已启动 表示网络服务已启动;还需用本项目客户端检查连接和游戏行为。按 Ctrl+C 正常停止。Linux 复制或解压后保留程序可执行权限,缺失时按操作系统方式设置。
先试本机示例时,可阅读包内 examples/server-map-test/README.md,按其中步骤执行 run.ps1;示例使用内存数据库,仍需要有效 Server 授权。压力测试示例不是普通启动的前置步骤。
程序可独立部署,不需要 Manager。r2 入门说明误写有“随包 systemd 材料或 Manager”,实际包中没有这些托管工具或服务单元;需要服务托管时另行选择适用工具。勘误见升级指南。
客户端开发与资源
客户端与服务端可独立存放。独立客户端项目可用 client init --project '..\客户端项目' --engine-root . 初始化;集中游戏项目使用已经生成的 editor 目录。
检查并打开开发输出:
.\tools\fc-tools.exe client check --project '..\我的游戏\editor' --engine-root .
.\tools\fc-tools.exe client dev --project '..\我的游戏\editor' --engine-root . --open-editor
检查退出码为 0 后,在打开的工程检查场景、脚本和资源;打开窗口不代表已经连接服务器。API 与示例以随包 sdk/client/client/README.md、sdk/client/examples/ 及各 SDK 的声明为准。客户端常用 @flexcore/client,服务端常用 @flexcore/server 和 @flexcore/module,不要把服务端专用依赖放入客户端。
场景、资源和声音调用使用 SDK 规定的标识。声音先在项目的 config/sound_catalog.json 声明 ID,再按 SDK 说明使用 audio.has、audio.playMusic 或 audio.playSfx。资源预取、异步准备、取消和缓存清理可参考随包 sdk/client/examples/resource-preparation.ts;预取完成不表示场景已经进入。
导出游戏客户端
从开发包根目录执行。输出目录需使用尚不存在的新目录,避免覆盖已交付成品。
Windows 示例:
.\tools\fc-tools.exe client publish --project '..\我的游戏\editor' --platform windows-x64 --engine-root . --release-root '..\客户端成品-windows'
Android 示例:
.\tools\fc-tools.exe client publish --project '..\我的游戏\editor' --platform android-arm64 --android-package-name 'com.examplegame.client' --engine-root . --release-root '..\客户端成品-android'
Android 的包名换成自己的实际应用包名,并先按编辑器导出设置准备 Android SDK、JDK 和应用签名。不要将引擎发行清单签名当作 Android 应用签名。
退出码为 0 后,按命令输出找到成品及生成的 发布说明.md。集中项目默认输出在游戏根的 output/client/,独立客户端项目默认在自身工程的 output/client/;指定 --release-root 时使用所选目录。导出后验证实际成品的启动、输入、声音和资源;Android 必须在目标设备安装检查。
r2 工具会按所选配置排除引擎授权材料与会话,保留正常游戏资源。开发者自行维护的数据库凭据、私钥或其他秘密仍需在发布前检查,不应放入客户端源资源。不要手工修改已签名成品及其校验文件来隐藏错误。
需要远程资源或私有素材时
不配置远程分发时,按普通客户端发布步骤打包。需要远程分包时,在项目配置中选择对应资源包和地址,按生成的 发布说明.md 部署文件,保持输出相对路径。资源站点需使用 HTTPS,支持所需的 Range、206 和 Content-Range 响应;先确认新文件可读,再切换版本入口。
私有资源通过所选 Auth 的资源领钥能力提供材料,与玩家登录分别配置。项目 client_tools.auth_config 选择实际 Auth 配置;密钥材料放在服务端,不能放入 SDK、客户端、公开资源目录或公开缓存。已有资源密码和密钥沿用原值;缺失时恢复原材料,不随意重建密码。改密码会影响旧客户端后续领钥。
发布时按输出同步服务端材料及对应配置,保留仍需支持的历史资源和密钥。纯公开资源发布不需要因此配置资源领钥;默认空置的可选资源配置不阻止普通玩家认证。更新失败时保留当前可用资源,游戏存档及数据库兼容由项目自身处理。
需要玩家登录时配置 Auth
仅领取编辑器或 Server 使用授权不需要 Auth。下面用于本机开发联调,先准备可连接的 MySQL 和 Redis,再创建一个新的配置目录:
.\auth\flexcore-auth.exe init --directory '..\玩家认证配置'
成功 JSON 中 success 为 true、result.status 为 initialized。默认本地初始化已生成开发密钥、证书与游戏服凭据,不要再对同一目录执行 key generate;已有输出不会被覆盖。
编辑生成目录中的 secrets/mysql.url 和 secrets/redis.url,填写实际连接。MySQL 的数据库名与 auth.toml 的 database.mysql_schema 一致;同一连接不要同时填写 URL 字段和 URL 文件字段。按配置说明核对认证域、公开地址、内部地址及游戏服标识。game-server-auth.toml 是游戏服配置片段,应合并到自己的实际配置。
依次执行:
.\auth\flexcore-auth.exe check --config '..\玩家认证配置\auth.toml'
.\auth\flexcore-auth.exe database migrate --config '..\玩家认证配置\auth.toml'
.\auth\flexcore-auth.exe doctor --config '..\玩家认证配置\auth.toml'
.\auth\flexcore-auth.exe --config '..\玩家认证配置\auth.toml'
check 返回 status: valid 表示配置和通信材料通过检查,不代表数据库已连接;迁移成功为 migrated,依赖检查成功为 healthy。启动日志出现 FlexCore认证服务已启动 后,检查所配置公开地址的 /health/ready,响应 status 为 ready,再验证本项目真实玩家登录。前台按 Ctrl+C 停止。
本地开发证书和默认地址不适合直接用于生产。生产需准备正式 HTTPS、服务之间相互验证身份的通信证书、数据库连接和签名材料;可用 init --credentials none 仅生成无秘密模板,再配置已有材料或按随包 docs/auth-service.md 准备。已有密钥不要重复生成。Linux 使用相应 flexcore-auth,配置路径规则与 Server 一致。
移动目录或换机器
正常停止受影响程序,再复制需要的程序及其依赖、项目、配置和数据。配置可与程序放在一起,也可用 --config 指向原位置;移动后检查相对路径、数据库地址、通信证书引用和实际文件访问情况,不要求固定目录或重新登记安装位置。
跨 Windows/Linux 部署使用对应平台程序,检查路径和运行依赖;客户端按目标平台重新导出。复制 Server 授权缓存时保留完整状态,在线刷新会话在目标平台按前述登录步骤准备。数据库内容用数据库自身的备份恢复方式处理,复制配置不会迁移数据库。
有外部 Auth、远程资源或其他服务时,分别核对访问地址和必要通信材料。引擎授权、玩家认证和资源领钥是不同操作,不互相代替,也无需因为闲置功能部署整套服务。
升级和恢复
按升级指南完成备份、校验、替换和重新生成客户端。保留游戏内容、秘密配置、密钥及有效授权。
恢复时先停止受影响进程,再恢复备份组件与兼容配置;数据库和存档是否支持旧程序须另行确认,不自动删除数据。授权已见撤销状态不得回退。远程资源也要保留恢复所需的对应文件。
遇到问题先看哪里
| 现象 | 检查与处理 |
|---|---|
| 网页确认后仍不能启动 | 回到原程序看领取及验签结果;确认所用账号有对应用途的有效权益,而非仅完成网页登录。 |
| 没有自动打开浏览器 | Windows 使用程序给出的链接;Linux 在另一台设备确认,保持原终端等待。 |
| 刷新失败 | 检查账号会话、网络和所选文件的实际读写情况。按明确提示重新登录,保留仍有效材料。 |
| 移动配置后找不到文件 | 对照所选配置目录解析相对路径,用 --config 或编辑器配置参数指向正确文件。 |
| 服务器未启动 | 查看本次错误涉及的字段、文件、端口或依赖;网络服务已启动 前不要当作服务已就绪。 |
| SDK 依赖或编译失败 | 从所选交付离线恢复依赖,核对 SDK 声明与实际程序兼容,不手改锁定摘要掩盖问题。 |
| 客户端资源、声音或连接异常 | 检查项目声明和生成的发布说明,重新导出后在实际成品测试;不要只检查编辑器窗口。 |
向官方论坛反馈时提供版本、操作步骤和脱敏错误说明,不公开密码、令牌、私钥、会话文件或完整数据库连接。
许可与随包参考
使用前请阅读并遵守随包的许可协议。
第三方许可保留原文。包内 docs/README.md 是参考入口,Auth、通信身份及兼容性说明在相应章节;SDK 示例位于各 SDK 自己的目录,按当前交付内容阅读。已公开版本的变化见版本记录,操作以本手册为准。
本文引用的发行资源尚未配置本站下载入口,目前仅显示资源名称;请从原发行渠道获取交付物并核对摘要。