lveyou/dl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
09786b9d85b1c59f08cd79ede9de77328d891ae7
dl/document/html/md_ai__skill.html
T
lveyou 4f643c1e7c 初始化内容
2026-09-16 14:07:40 +08:00

244 lines
17 KiB
HTML
Vendored
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.13.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>dl: AI Skill：dl 引擎开发指南</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">dl
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- 制作者 Doxygen 1.13.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',false,false,'search.php','搜索',false);
});
/* @license-end */
</script>
<div id="main-nav"></div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){ initResizable(false); });
/* @license-end */
</script>
</div><!-- top -->
<div id="doc-content">
<div><div class="header">
<div class="headertitle"><div class="title">AI Skill：dl 引擎开发指南</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>本文档面向开发者与 AI，记录 dl 引擎的整体架构、代码风格、通用易错点与常规使用方法，便于快速上手并保持一致。</p>
<h1>一、整体架构</h1>
<h2>1. 项目定位</h2>
<p>dl（drawing library）是基于 C++23 的开发框架/游戏引擎，命名空间统一为 <code>dl</code>，集成了大量 C/C++ 开源库。</p>
<h2>2. 目录结构</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">目录 </th><th class="markdownTableHeadLeft">职责 </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>base/</code> </td><td class="markdownTableBodyLeft">基础类型与容器（Array、String、Color、Vector 等） </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>io/</code> </td><td class="markdownTableBodyLeft">输入输出（日志、文件、网络、JSON/XML/XLSX、数据库） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>math/</code> </td><td class="markdownTableBodyLeft">数学与物理（Mesh、Guid、Physics） </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>memory/</code> </td><td class="markdownTableBodyLeft">内存管理（Buffer、加密、流、对象复用） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>misc/</code> </td><td class="markdownTableBodyLeft">杂项（Mod、JsonConfig、Tilemap、AStar） </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>render/</code> </td><td class="markdownTableBodyLeft">渲染（Graphics、Factory、Action、Animation、粒子） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>script/</code> </td><td class="markdownTableBodyLeft">脚本（Lua、AngelScript） </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>system/</code> </td><td class="markdownTableBodyLeft">系统（Engine、System 窗口、音频、线程、硬件信息） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>tool/</code> </td><td class="markdownTableBodyLeft">工具（DebugInfo、Archiver 等） </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ui/</code> </td><td class="markdownTableBodyLeft">UI 系统（Manager、Scene） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>vk/</code> </td><td class="markdownTableBodyLeft">Vulkan 渲染底层 </td></tr>
</table>
<h2>3. 头文件组织</h2>
<ul>
<li>总头文件为 <code><a class="el" href="dl_8h.html" title="dl游戏引擎">dl.h</a></code>，也可按模块单独包含（<code><a class="el" href="dl__type_8h.html" title="通用类型">dl_type.h</a></code>、<code><a class="el" href="dl__io_8h.html" title="io相关">dl_io.h</a></code>、<code><a class="el" href="dl__render_8h.html" title="绘图">dl_render.h</a></code>、<code><a class="el" href="dl__ui_8h.html" title="ui系统">dl_ui.h</a></code>、<code><a class="el" href="dl__range_8h.html" title="范围操作">dl_range.h</a></code>）。</li>
<li>模块聚合头位于 <code>dl/</code> 根目录，具体类头位于各子目录。</li>
</ul>
<h2>4. 程序入口</h2>
<ul>
<li>平台入口已统一封装在 <code><a class="el" href="dl__main_8h.html" title="平台入口函数统一">dl_main.h</a></code>：根据平台自动生成 <code>main</code> / <code>WinMain</code> / <code>android_main</code>，用户只需实现 <code>int <a class="el" href="dl__main_8h.html#a3cf9378cca29c8d6cf65f20e8a4007c0">Main()</a></code>。</li>
<li>入口内部会调用 <code>dl_main_init</code>（初始化崩溃采集、解析命令行参数）与 <code>dl_main_release</code>。</li>
</ul>
<h2>5. 全局对象约定</h2>
<ul>
<li>各子系统通过 <code>extern</code> 全局**指针**暴露，命名统一 <code>g_</code> 前缀：<code>g_system</code>、<code>g_factory</code>、<code>g_gfx</code>、<code>g_input</code>、<code>g_log</code>、<code>g_audio</code>、<code>g_lua</code>、<code>g_as</code>、<code>g_net</code>、<code>g_http</code>、<code>g_ui</code>、<code>g_physics</code>、<code>g_time</code>、<code>g_thread</code> 等。</li>
<li>用指针而非全局对象，是为了控制生命周期、不占用全局空间。</li>
<li>这些对象的生命周期由 <code>Engine::Init</code> / <code>Engine::Release</code> 统一管理，<code>Release</code> 之后不可再访问。</li>
</ul>
<h1>二、代码风格</h1>
<h2>1. 命名规范</h2>
<ul>
<li>全局函数：小写 + 下划线，如 <code>calc_n</code>。</li>
<li>非通用型全局函数：仅首字母小写，如 <code>createQuad</code>。</li>
<li><code>dl</code> 命名空间内的全局函数：大写开头，如 <code>Math::SetSeed</code>。</li>
<li>宏：无命名空间，必须 <code>DL_</code> 开头防止冲突。</li>
<li>类/类型：首字母大写；缩写只首字母大写（如 <code>UI</code>）；除 <code>dl</code> 外的其他命名空间也首字母大写。</li>
<li>成员变量：下划线前缀，如 <code>_mulSpr</code>。</li>
</ul>
<h2>2. 常用语义区分</h2>
<ul>
<li><code>init</code>：不需要外部资源的初始化；<code>load</code>：需要使用外部资源的初始化。</li>
<li><code>Add</code>：添加一个**已有**对象，而非创建。</li>
<li><code>func</code>：回调函数；<code>fn</code>：局部 lambda。</li>
<li><code>Refresh</code>：刷新（不保存数据）；<code>Set</code>：设置。</li>
<li><code>Update</code>：时间片逻辑；<code>Render</code>：绘制；<code>Run</code>：前二者合一（一般不使用）。</li>
<li><code>Reset</code>：重置；<code>Delete</code>：删除（不可逆）；<code>Clear</code>：清除；<code>Release</code>：释放。</li>
<li><code>Clone</code>：新建元素复制；<code>Copy</code>：把属性复制到已有元素。</li>
<li><code>GetBuffer</code>：返回字节流；<code>GetData</code>：返回实际类型指针。</li>
<li>多个元素不加复数，用 <code>mul</code> 修饰（如 <code>_mulSpr</code>，可为数组或链表）。</li>
</ul>
<h2>3. 命名约定补充</h2>
<ul>
<li>加减乘除：<code>add</code> / <code>sub</code> / <code>mul</code> / <code>div</code>。</li>
<li>冒号 <code>:</code> 用作特殊对象的隐含命名，如默认精灵/默认演员名为 <code>":"</code>。</li>
<li>资源名中 <code>/</code> 不能作文件名，用 <code>.</code> 替换。</li>
</ul>
<h2>4. 基础类型与编码</h2>
<ul>
<li>优先使用 <code>int</code>、<code>unsigned</code>、<code>float</code>；字节流用 <code>std::byte</code>（配合 <code>Buffer</code> 类）。</li>
<li>字符串统一 UTF-8（<code>std::string</code>），需要拆分字符时再转 UTF-32（用 iconv）。</li>
<li>文件优先 <code>fstream</code>；接口统一 UTF-8。</li>
<li>优先使用枚举类（<code>enum class</code>）。</li>
</ul>
<h2>5. 类成员顺序</h2>
<p>嵌套类 → 构造函数 → 操作符重载 → 主要函数 → Set 函数 → Get 函数 → 功能性函数 → 析构函数 → 私有成员 → 私有函数。</p>
<h2>6. 对象创建与释放</h2>
<ul>
<li>特殊对象通过 <code>g_factory</code> 创建，用户层一般情况不出现 <code>new</code>。</li>
</ul>
<h1>三、通用易错点</h1>
<h2>1. 生命周期顺序</h2>
<p><code>Engine::Release()</code> 会释放（<code>delete</code>）所有 <code>g_</code> 全局对象。任何对全局对象的操作（如 <code>g_system-&gt;Pause()</code>）必须在 <code>Release()</code> **之前**，否则出现悬空指针。</p>
<h2>2. 越界判断语义（易搞反）</h2>
<ul>
<li><code>IsOutRange</code> 越界返回 **true**。</li>
<li><code>CheckRange</code> 越界返回 **false**。</li>
</ul>
<p>两者语义相反，注意区分。</p>
<h2>3. init 与 load 的区别</h2>
<p><code>init</code> 不依赖外部资源，<code>load</code> 依赖外部资源。命名用错会导致对资源加载时机的误解。</p>
<h2>4. 全局对象是裸指针</h2>
<p><code>g_system</code> 等是裸指针而非引用，使用前需确认已初始化；<code>Release</code> 后立即失效。</p>
<h2>5. 资源路径与命名</h2>
<ul>
<li>资源名中的 <code>/</code> 需用 <code>.</code> 替换（<code>/</code> 不能作文件名）。</li>
<li><code>Factory::SetPath</code> 只能在 <code>System::Start</code> 之前调用一次。</li>
</ul>
<h1>四、常规使用方法</h1>
<h2>1. 最小入口</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="dl_8h.html">dl.h</a>&gt;</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> <a class="code hl_function" href="dl__main_8h.html#a3cf9378cca29c8d6cf65f20e8a4007c0">Main</a>()</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// 可选：配置引擎，如 dl::Engine::GetParamRef()._useAudio = false;</span></div>
<div class="line"> <a class="code hl_function" href="classdl_1_1_engine.html#a7cfd7be45b8ec1036dca057c23e9a950">dl::Engine::Init</a>();</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> <a class="code hl_function" href="classdl_1_1_engine.html#a5e41fa9846b80719dd1e8185fd79e064">dl::Engine::Release</a>();</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="ttc" id="aclassdl_1_1_engine_html_a5e41fa9846b80719dd1e8185fd79e064"><div class="ttname"><a href="classdl_1_1_engine.html#a5e41fa9846b80719dd1e8185fd79e064">dl::Engine::Release</a></div><div class="ttdeci">static void Release()</div></div>
<div class="ttc" id="aclassdl_1_1_engine_html_a7cfd7be45b8ec1036dca057c23e9a950"><div class="ttname"><a href="classdl_1_1_engine.html#a7cfd7be45b8ec1036dca057c23e9a950">dl::Engine::Init</a></div><div class="ttdeci">static void Init()</div></div>
<div class="ttc" id="adl_8h_html"><div class="ttname"><a href="dl_8h.html">dl.h</a></div><div class="ttdoc">dl游戏引擎</div></div>
<div class="ttc" id="adl__main_8h_html_a3cf9378cca29c8d6cf65f20e8a4007c0"><div class="ttname"><a href="dl__main_8h.html#a3cf9378cca29c8d6cf65f20e8a4007c0">Main</a></div><div class="ttdeci">int Main()</div></div>
</div><!-- fragment --><h2>2. 进入游戏循环</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="dl_8h.html">dl.h</a>&gt;</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span> OnInit() { <span class="comment">/* 初始化资源 */</span> }</div>
<div class="line"><span class="keywordtype">void</span> OnRun() { <span class="comment">/* 每帧逻辑 */</span> }</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> <a class="code hl_function" href="dl__main_8h.html#a3cf9378cca29c8d6cf65f20e8a4007c0">Main</a>()</div>
<div class="line">{</div>
<div class="line"> <a class="code hl_function" href="classdl_1_1_engine.html#a7cfd7be45b8ec1036dca057c23e9a950">dl::Engine::Init</a>();</div>
<div class="line"> <a class="code hl_variable" href="namespacedl.html#ab7afa4571bbf2c18a00e8359c8000bff">dl::g_system</a>-&gt;SetFuncInit(OnInit);</div>
<div class="line"> <a class="code hl_variable" href="namespacedl.html#ab7afa4571bbf2c18a00e8359c8000bff">dl::g_system</a>-&gt;SetFuncRun(OnRun);</div>
<div class="line"> <a class="code hl_variable" href="namespacedl.html#ab7afa4571bbf2c18a00e8359c8000bff">dl::g_system</a>-&gt;Start(); <span class="comment">// 创建窗口并进入游戏循环</span></div>
<div class="line"> <a class="code hl_function" href="classdl_1_1_engine.html#a5e41fa9846b80719dd1e8185fd79e064">dl::Engine::Release</a>();</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="ttc" id="anamespacedl_html_ab7afa4571bbf2c18a00e8359c8000bff"><div class="ttname"><a href="namespacedl.html#ab7afa4571bbf2c18a00e8359c8000bff">dl::g_system</a></div><div class="ttdeci">System * g_system</div></div>
</div><!-- fragment --><h2>3. 常用全局对象</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">对象 </th><th class="markdownTableHeadLeft">用途 </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>g_system</code> </td><td class="markdownTableBodyLeft">窗口、游戏循环、暂停、剪贴板、截屏 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>g_factory</code> </td><td class="markdownTableBodyLeft">资源工厂（精灵/模型/字体等的加载与创建） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>g_gfx</code> </td><td class="markdownTableBodyLeft">绘图 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>g_input</code> </td><td class="markdownTableBodyLeft">输入（鼠标/键盘） </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>g_log</code> </td><td class="markdownTableBodyLeft">日志 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>g_audio</code> / <code>g_midi</code> </td><td class="markdownTableBodyLeft">音频 / MIDI </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>g_lua</code> / <code>g_as</code> </td><td class="markdownTableBodyLeft">Lua / AngelScript 脚本 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>g_net</code> / <code>g_http</code> </td><td class="markdownTableBodyLeft">网络 / HTTP </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>g_physics</code> </td><td class="markdownTableBodyLeft">物理 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>g_time</code> </td><td class="markdownTableBodyLeft">时间 </td></tr>
</table>
<h2>4. 基础类型速查</h2>
<ul>
<li><code>Point</code> = <code>Array&lt;int,2&gt;</code>，<code>Size</code> = <code>Array&lt;unsigned,2&gt;</code>，<code>Position</code> = <code>Array&lt;float,2&gt;</code>，<code>Color</code> = <code>Array&lt;float,4&gt;</code>（rgba）。</li>
<li><code>Rect</code> = <code>Point4</code>，<code>RectF</code> = <code>Position4</code>。</li>
<li><code>Float = float</code>，<code>FloatTime = float</code>。</li>
<li>字面量后缀：<code>_f</code>（Float）、<code>_ft</code>（FloatTime）、<code>_zu</code>（size_t）。</li>
</ul>
<h2>5. 单元测试</h2>
<ul>
<li>使用 googletest，测试入口为 <code>project/dl_unit_test/test_main.cpp</code>。</li>
<li><code>dl_unit_test</code> 目标开启 <code>USE_RENDER</code>，会链接渲染相关依赖。</li>
<li>测试完成后可调用 <code>g_system-&gt;Pause()</code> 暂停观察结果（注意需在 <code>Engine::Release()</code> 之前）。 </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
制作者&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.1
</small></address>
</div><!-- doc-content -->
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink