Unison Engine API

Appearance

快速开始 ​

本文档帮助你在 5 分钟内启动第一个 Unison Engine 项目。

1. 获取发布包 ​

从发布渠道获取引擎发布包，解压后得到如下目录：

MyGame/
├── launcher.exe                  # 启动器
├── unison.xml                    # 配置文件
└── bin/                          # 引擎运行时（不需要动）

你需要自己创建两个目录：

MyGame/
├── scene/                        # 场景入口（存放 init.py）
└── Scripts/                      # 游戏脚本

2. 配置 unison.xml ​

创建一个最小化的 unison.xml：

xml
<ppg3d>
    <pymodules>
        <module name="exio3">
            <function name="add_cpk_to_cpkhub" type="vfs.mount"/>
            <function name="get_file" type="vfs.get_file"/>
            <function name="find_file" type="vfs.find_file"/>
            <function name="list_dir" type="vfs.list_dir"/>
            <function name="get_doc_dir" type="vfs.get_doc_dir"/>
            <function name="get_real_path" type="vfs.get_real_path"/>
        </module>
    </pymodules>
    <client WindowClientWidth="1280" WindowClientHeight="720"/>
    <python ThreadEnable="True"/>
    <log FileName="%WORK_DIR%/log_inst_%INST%.txt"
         OldFileName="%WORK_DIR%/log_old_%ROTATE%.txt"
         NormalFileName="%WORK_DIR%/log.txt"
         MaxOldNumber="5"/>
    <filesystems>
        <filesystem name="scene" type="scene">
            <loader root="%WORK_DIR%/scene"/>
        </filesystem>
        <filesystem name="Scripts" type="script">
            <loader root="%WORK_DIR%/Scripts"/>
        </filesystem>
        <filesystem name="Lib" type="Lib" fsapi="exio3" key="-231">
            <loader root="%WORK_DIR%/Lib"/>
        </filesystem>
        <filesystem name="fonts" type="res" fsapi="exio3">
            <loader root="%WORK_DIR%/builtin_res_0"/>
        </filesystem>
    </filesystems>
</ppg3d>
关键项说明
WindowClientWidth/Height窗口分辨率
name="scene"场景目录，挂载点为 scene/，存放场景模块
name="Scripts"脚本目录，挂载点为 Scripts/，存放 init.py 和游戏逻辑

更详细的配置说明见 unison.xml 配置。

3. 编写入口脚本 ​

在 Scripts/ 目录下创建 init.py：

python
import unison.excore
import unison.cocosui as ccui
import unison.config as cfg
import builtins

w, h = cfg.settings.window_width, cfg.settings.window_height
title = "Hello World"

def on_start():
    unison.excore.create_window(title, w, h)
    ccui.initialize()

引擎启动后会在 sys.path 中按 <filesystems> 顺序搜索 init.py，找到后自动调用 on_start()。

在 Scripts/ 目录下创建 main.py：

python
import unison.excore as game3d
import unison.cocosui as ccui
import unison.render as render

w = builtins.game_width
h = builtins.game_height

def on_start():
    ccui.set_design_resolution(w, h)
    text = ccui.create_text_with_font('hello',w/2,h/2,24,"Hello, World",'fonts/arial.ttf')

def on_update(dt):
    render.update_logic_fps(dt)

def on_render():
    render.begin_scene(0.0, 0.0, 0.0, 1.0)
    ccui.update(1.0 / game3d.get_frame_limit())
    render.end_scene()

def on_shutdown():
    ccui.shutdown()

4. 启动游戏 ​

双击 launcher.exe，引擎自动加载配置并执行场景入口。

下一步 ​