This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
如果需要使用 Lua 本身不提供的功能, 比如第三方软件交互或者底层硬件控制, Defold SDK 接受使用 C, C++, Objective C, Java 以及 Javascript 编写的扩展程序, 语言选取取决于目标发布平台. 原生扩展的常见用法有:
Defold 提供了一个云端服务器编译方案. 游戏项目的各种依赖, 或者直接引用或者通过 库项目 加入, 都会变成项目内容的一部分. 没有必要重新编译特别版引擎然后分发给开发组成员, 任何成员对项目的编译运行使所有成员都能得到嵌入全部所需库的引擎程序.
Defold 免费提供云编译服务器, 没有使用限制. 服务器托管于欧洲, 代码上传的 URL 可以在 编辑器首选项窗口 进行设置, 或者用命令行工具 bob 设置 --build-server
参数进行指定. 关于云编译服务器及假设私人编译服务器的详情请参考 GitHub 上的介绍.
在项目根目录下为扩展程序建立一个文件夹. 这个文件夹将包含扩展程序所需要的一切, 源代码, 外部库和资源文件. 云编译服务器解析这个结构以便分别获取所需要的各种文件.
myextension/
│
├── ext.manifest
│
├── src/
│
├── include/
│
├── lib/
│ └──[platforms]
│
├── manifests/
│ └──[platforms]
│
└── res/
└──[platforms]
platform
或 architecure-platform
的子文件夹分类放置, 也就是说什么平台用什么库.
支持的系统有 ios
, android
, osx
, win32
, linux
, web
.
支持的 arc-platform
平台架构有 armv7-ios
, arm64-ios
, x86_64-ios
, armv7-android
, arm64-android
, x86-osx
, x86_64-osx
, x86-win32
, x86_64-win32
, x86_64-linux
, js-web
和 wasm-web
.
platform
或 architecure-platform
的子文件夹分类放置, 也就是说什么平台用什么资源. 其中 common
文件夹包含各种平台的通用资源文件.manifests 包含编译时不同平台所需的配置文件. 配置文件要根据称为 platform
的子文件夹分类放置:
android
- 这里存放片段配置文件用以与主配置文件混合 (就像这里介绍的那样). 还可以存放 build.gradle
文件及其依赖以便 Gradle 可以解析 (示例). 还能存放0个或多个 ProGuard 代码混淆文件 (试验功能).ios
- 这里存放片段配置文件用以与主配置文件混合 (就像这里介绍的那样).osx
- 这里存放片段配置文件用以与主配置文件混合 (就像这里介绍的那样).web
- 这里存放片段配置文件用以与主配置文件混合 (就像这里介绍的那样).原生扩展如同其他资源文件一样也可以共享. 如果库项目包含原生扩展文件夹的话, 它就能作为项目依赖库共享给其他人. 详情请见 库项目教程.
从头开始做一个简单的原生扩展. 第一步, 创建 myextension 文件夹并加入 ext.manifest 文件, 文件中包含扩展名 “MyExtension”. 注意这个扩展名会作为一个 C++ 变量名填充在 DM_DECLARE_EXTENSION
宏的第一个参数位置上 (见下文).
# C++ symbol in your extension
name: "MyExtension"
这个扩展就一个 C++ 文件, myextension.cpp, 位于 “src” 文件夹里.
源代码如下:
// myextension.cpp
// Extension lib defines
#define LIB_NAME "MyExtension"
#define MODULE_NAME "myextension"
// include the Defold SDK
#include <dmsdk/sdk.h>
static int Reverse(lua_State* L)
{
// The number of expected items to be on the Lua stack
// once this struct goes out of scope
DM_LUA_STACK_CHECK(L, 1);
// Check and get parameter string from stack
char* str = (char*)luaL_checkstring(L, 1);
// Reverse the string
int len = strlen(str);
for(int i = 0; i < len / 2; i++) {
const char a = str[i];
const char b = str[len - i - 1];
str[i] = b;
str[len - i - 1] = a;
}
// Put the reverse string on the stack
lua_pushstring(L, str);
// Return 1 item
return 1;
}
// Functions exposed to Lua
static const luaL_reg Module_methods[] =
{
{"reverse", Reverse},
{0, 0}
};
static void LuaInit(lua_State* L)
{
int top = lua_gettop(L);
// Register lua names
luaL_register(L, MODULE_NAME, Module_methods);
lua_pop(L, 1);
assert(top == lua_gettop(L));
}
dmExtension::Result AppInitializeMyExtension(dmExtension::AppParams* params)
{
return dmExtension::RESULT_OK;
}
dmExtension::Result InitializeMyExtension(dmExtension::Params* params)
{
// Init Lua
LuaInit(params->m_L);
printf("Registered %s Extension\n", MODULE_NAME);
return dmExtension::RESULT_OK;
}
dmExtension::Result AppFinalizeMyExtension(dmExtension::AppParams* params)
{
return dmExtension::RESULT_OK;
}
dmExtension::Result FinalizeMyExtension(dmExtension::Params* params)
{
return dmExtension::RESULT_OK;
}
// Defold SDK uses a macro for setting up extension entry points:
//
// DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)
// MyExtension is the C++ symbol that holds all relevant extension data.
// It must match the name field in the `ext.manifest`
DM_DECLARE_EXTENSION(MyExtension, LIB_NAME, AppInitializeMyExtension, AppFinalizeMyExtension, InitializeMyExtension, 0, 0, FinalizeMyExtension)
注意 DM_DECLARE_EXTENSION
宏用来声明扩展程序执行入口. 第一个参数 symbol
要与 ext.manifest 上的扩展名一致. 本例中没有用到 “update” 或 “on_event” 执行入口, 所以用 0
填充了宏的相应参数.
现在就差编译运行了 (Project ▸ Build). 带原生扩展的项目会被上传到云编译服务器编译. 如果编译出错, 将会弹出一个包含错误信息的窗口.
测试扩展运行, 新建一个游戏对象和一个脚本组件, 再写一些测试代码:
local s = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
local reverse_s = myextension.reverse(s)
print(reverse_s) --> ZYXWVUTSRQPONMLKJIHGFEDCBAzyxwvutsrqponmlkjihgfedcba
成功了! 我们从零开始完整地制作了一个扩展程序.
上面提到了 DM_DECLARE_EXTENSION
宏用来声明程序执行入口:
DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)
入口对应扩展程序的各种生命周期函数, 运行顺序如下:
app_init
init
- Defold API 初始化. 建议扩展程序从这里开始运行并且暴露给Lua脚本.init()
函数调用.update
update()
函数调用.on_event
final()
函数调用.final
app_final
编译器中预定义了如下平台标识:
当项目使用了原生扩展, 编译时就会生成编译服务器日志. 编译服务器日志文件 (log.txt
) 与被编译的项目一起下载到本地, 并保存在项目 build 文件夹的 .internal/%platform%/build.zip
文件中.
除了扩展名称, ext.manifest 文件还可以包含指定平台的编译参数, 链接参数, 外部程序和链接库. 如果 ext.manifest 文件不包含 “platforms” 项, 或者找不到对应的平台配置参数, 编译仍会继续, 只是不加各种编译参数.
Here is an example:
name: "AdExtension"
platforms:
arm64-ios:
context:
frameworks: ["CoreGraphics", "CFNetwork", "GLKit", "CoreMotion", "MessageUI", "MediaPlayer", "StoreKit", "MobileCoreServices", "AdSupport", "AudioToolbox", "AVFoundation", "CoreGraphics", "CoreMedia", "CoreMotion", "CoreTelephony", "CoreVideo", "Foundation", "GLKit", "JavaScriptCore", "MediaPlayer", "MessageUI", "MobileCoreServices", "OpenGLES", "SafariServices", "StoreKit", "SystemConfiguration", "UIKit", "WebKit"]
flags: ["-stdlib=libc++"]
linkFlags: ["-ObjC"]
libs: ["z", "c++", "sqlite3"]
defines: ["MY_DEFINE"]
armv7-ios:
context:
frameworks: ["CoreGraphics", "CFNetwork", "GLKit", "CoreMotion", "MessageUI", "MediaPlayer", "StoreKit", "MobileCoreServices", "AdSupport", "AudioToolbox", "AVFoundation", "CoreGraphics", "CoreMedia", "CoreMotion", "CoreTelephony", "CoreVideo", "Foundation", "GLKit", "JavaScriptCore", "MediaPlayer", "MessageUI", "MobileCoreServices", "OpenGLES", "SafariServices", "StoreKit", "SystemConfiguration", "UIKit", "WebKit"]
flags: ["-stdlib=libc++"]
linkFlags: ["-ObjC"]
libs: ["z", "c++", "sqlite3"]
defines: ["MY_DEFINE"]
各个平台可用参数项如下:
frameworks
- 加入苹果库 (iOS 和 OSX)flags
- 编译参数linkFlags
- 链接参数libs
- 链接库defines
- 编译预定义aaptExtraPackages
- 导入外部包 (Android)aaptExcludePackages
- 排除内部包 (Android)aaptExcludeResourceDirs
- 排除资源文件夹 (Android)Defold 资源中心 也包含有许多原生扩展项目资源.
Did you spot an error or do you have a suggestion? Please let us know on GitHub!
GITHUB