eepp - Entropia Engine++

eepp 是一个开源的跨平台游戏与应用开发 框架，专注于开发丰富的图形用户界面。

功能

跨平台功能

• 官方支持 Linux、Windows、macOS、FreeBSD、Haiku、Android 和 iOS。

• 使用 emscripten 导出为 HTML5，存在一些轻微限制。

UI 模块

• 基础控件，用于将应用程序/游戏对象作为节点进行管理，并支持所有基本输入交互事件（点击、按键、鼠标悬停、焦点等）。

• 功能完备的 UI 系统，支持动画、缩放、旋转、裁剪、事件、消息等。

• 支持主题和皮肤/装饰。

• 支持像素密度（根据屏幕的像素密度对 UI 元素进行缩放）。

• 已实现所有基础控件（按钮、文本框、组合框、输入框、菜单、列表框、滚动条等）。

• 支持绘制失效。可用于开发实际应用程序，资源占用低（仅在需要时重绘）。

• 布局系统类似于 Android 布局（LinearLayout、RelativeLayout、GridLayout）。

• 高级功能，如文本选择、复制粘贴和按键绑定。

• 从 XML 加载并设置布局样式

• 使用层叠样式表（CSS）进行样式设置

• HTML+CSS 兼容层（针对原生 HTML 内容渲染的持续工作）：

  • 使用 UIWebView 组件原生渲染 HTML 文档。也用于 UIMarkdownView 的 Markdown 渲染。
  • 完整的 CSS 布局系统，涵盖 block、inline、inline-block、flex（Flexbox Level 1）、inline-flex、grid、inline-grid、table、list-item 和 none 显示模式。
  • 定位：absolute、fixed、float、relative 和 sticky。
  • 富文本格式化，支持内联文本跨度、换行、自定义块、浮动和基线对齐。
  • CSS 属性：背景（颜色/图像/图层）、边框、盒模型（margin/padding）、尺寸约束（min/max-width/height）、box-sizing、overflow、visibility、z-index、文本样式（颜色、字体、装饰、对齐）等。
  • 文档作用域样式表、CSS 视口/媒体查询以及作用域 @font-face 字体资源。
  • 在已实现的部分符合规范。遵循 CSS 和 HTML Living Standard 规范，而非自定义行为。

图形模块

• OpenGL 2（固定管线）、OpenGL 3（可编程管线）、OpenGL ES 2、OpenGL ES 1 和 OpenGL Core Profile 的渲染器。

• 批量渲染器（所有渲染均由引擎自动批处理）。

• 字体支持（TrueType、BMFont 和 XNA Fonts）。

• 帧缓冲支持。

• 着色器支持（带有从固定管线着色器到可编程着色器的自动转换器）。

• 顶点缓冲对象支持。

• 粒子系统。

• 可扩展控制台。

• 动画精灵。

• 纹理图集支持（自动创建和更新纹理图集，包含编辑器）。

• 裁剪蒙版（模板、剪刀、平面）

• 九宫格可缩放位图支持。

• 图元可绘制对象。

• 支持多种图像格式（包含光栅化 SVG），支持压缩纹理（在可能的情况下直接上传到 GPU）。

Window Module

• 基于后端的模块，这意味着您可以轻松创建用于窗口/输入处理的后端。

• 当前支持 SDL 2 作为后端。

• 剪贴板支持。

• 硬件光标。

• 显示管理器

• 摇杆支持。

Audio Module

• 基于 OpenAL 的音频引擎，支持可扩展的文件格式。支持 OGG 和 Wav 的读写，支持 MP3 和 FLAC 的读取。

System Module

• 提供库完全多线程支持所需的所有基础功能，包括打包的文件格式支持、时钟、资源管理器、翻译器以及更多功能。

• 虚拟文件系统类（将抽象的资源提供程序整合到一个虚拟文件系统中，将 zip 文件和本地文件系统抽象为一个，以实现资源的透明加载，类似于 PhysicsFS）。

Core Module

• 可定制的内存管理器。在调试模式下默认使用，用于跟踪内存泄漏。

• 支持 UTF8、UTF-16、UTF-32、Ansi、Wide Char。

• 字符串类，内部使用 UTF-32 字符。

• 调试宏

Math Module

• 通用函数和模板（向量、四边形、多边形等）。

• 带缓动的插值类。

• 一些小型数学工具，包括梅森旋转随机数生成器实现、柏林噪声等。

网络模块

• 使用 HTTP 客户端的 Web 请求，支持 TLS（由 mbedtls 或 openssl 提供）。

• 异步 HTTP 请求。

• 使用 FTP 客户端和 FTPS 客户端（带显式 TLS 的 FTP）进行文件传输。

• TCP 和 UDP 套接字。

• 支持 HTTP Content-Encoding 和 Transfer-Encoding。

• 支持 HTTP 代理。

• 支持 HTTP 压缩响应。

• 还支持 HTTP 断点续传下载和自动跟随重定向。

场景模块

• 基于节点的系统，便于管理场景。

• 完全控制节点事件（点击、鼠标悬停、焦点等）。

• 事件系统。

• 节点消息系统。

• 节点的可编程动作（淡入淡出、旋转、移动、缩放等）。

物理模块（可选）

• 完整的 OOP chipmunk 物理封装。

地图模块（可选）

• 带软件动态光照的 Tiled 地图。

• 功能齐全的地图编辑器。

工具

• 非常简单的 UI 编辑器。从 XML 文件加载布局，并实时查看所做的更改。

• 纹理图集编辑器。一个非常简单的工具，允许开发者创建和编辑纹理图集。

• Map Editor：一个高级但简单的游戏引擎地图编辑器。由于我没有时间继续开发，它缺少一些功能，这个特定工具很可能在不久的将来会被 TMX 地图支持所取代（但我不喜欢 TMX 地图，所以目前还没有决定）。

通用功能

• 支持多线程资源加载（纹理、声音、字体等）。

文档

文档位于此处。我目前正在 改进它。目前项目约 50% 已有文档，因此仍需 大量工作。请查看位于 src/examples 的代码示例， 你也可以查看测试（src/test）和工具（src/tools）。

我正在努力改进 UI 模块的文档，因为 目前它是项目中最重要且最复杂的模块，但缺乏适当的 文档。如果你有任何问题，可以随时联系我。

获取代码

该仓库使用 git 子模块，因此你需要克隆仓库及其 子模块，为了轻松实现这一点，你可以简单地使用以下命令克隆：

git clone --recurse-submodules https://github.com/SpartanJ/eepp.git

UI 截图

ecode - 代码编辑器

ecode 是一款受 lite 启发的代码编辑器。 它使用了基于默认 Plasma 深色主题的最新纯 CSS 主题：Breeze Dark。

UI 编辑器

一个实时显示任何布局和 CSS 变更的编辑器，旨在加速用户界面的开发。截图中展示了 eepp 中可用的一些默认控件。

纹理图集编辑器

小型工具，用于创建和编辑纹理图集。

地图编辑器

使用默认皮肤主题（使用包含 9 宫格图像的单个纹理图集）的 2D 地图编辑器。

UI 布局 XML 示例

对于任何 Android 开发者来说，这应该看起来非常熟悉。这是一个窗口， 其中包含垂直线性布局显示的最基本控件。

<window layout_width="300dp" layout_height="300dp" window-flags="default|maximize|shadow">
  <LinearLayout id="testlayout" orientation="vertical" layout_width="match_parent" layout_height="match_parent" layout_margin="8dp">
	<TextView text="Hello World!" gravity="center" layout_gravity="center_horizontal" layout_width="match_parent" layout_height="wrap_content" backgroundColor="black" />
	<PushButton text="OK!" textSize="16dp" icon="ok" gravity="center" layout_gravity="center_horizontal" layout_width="match_parent" layout_height="wrap_content" />
	<Image src="thecircle" layout_width="match_parent" layout_height="32dp" flags="clip" />
	<Sprite src="gn" />
	<TextInput text="test" layout_width="match_parent" layout_height="wrap_content" />
	<DropDownList layout_width="match_parent" layout_height="wrap_content" selectedIndex="0">
	  <item>Test Item</item>
	  <item>@string/test_item</item>
	</DropDownList>
	<ListBox layout_width="match_parent" layout_height="match_parent" layout_weight="1">
	  <item>Hello!</item>
	  <item>World!</item>
	</ListBox>
  </LinearLayout>
</window>

UI 介绍可参见此处。

带有 C++ 示例的 UI 控件

使用实际代码时是什么样子？

UITextView::New()->setText( "Text  on  test  1" )
		 ->setCharacterSize( 12 )
		 ->setLayoutMargin( Rect( 10, 10, 10, 10 ) )
		 ->setLayoutSizePolicy( SizePolicy::MatchParent, SizePolicy::WrapContent )
		 ->setParent( layout );

UI 样式

元素样式可以通过级联样式表（Cascading Style Sheets）的自定义实现来完成，大多数常见的 CSS2 规则均可用，此外还支持若干 CSS3 规则（一些示例：动画、 过渡、 自定义属性、 媒体查询、 @font-face 规则、 :root 元素）。 下面是一个展示 CSS 外观的小型示例：

@font-face {
  font-family: "OpenSans Regular";
  src: url("https://raw.githubusercontent.com/SpartanJ/eepp/develop/bin/assets/fonts/OpenSans-Regular.ttf");
}

@import url("assets/layouts/imported.css") screen and (min-width: 800px);

:root {
  --font-color: black;
  --background-input-color: rgba(255, 255, 255, 0.7);
  --border-color: black;
  --border-width: 1dp;
}

.screen TextView {
  color: var(--font-color);
}

.form {
  background-image: @drawable/back;
  background-repeat: no-repeat;
  background-size: cover;
}

.form .form_inputs {
  background-color: var(--non-existent, var(--background-input-color));
  margin-left: 100dp;
  margin-right: 100dp;
  padding-top: 72dp;
  padding-left: 57dp;
  padding-right: 57dp;
  padding-bottom: 115dp;
}

.screen TextView.input,
.screen TextInput.input {
  font-family: AkzidenzGroteskBQ-Cnd;
  layout-width: match_parent;
  layout-height: 80dp;
  border-color: var(--border-color);
  border-width: var(--border-width);
  color: var(--font-color);
  padding-left: 40dp;
  padding-right: 40dp;
  margin-bottom: 32dp;
  skin: none;
  hint-font-family: AkzidenzGroteskBQ-Cnd;
  hint-font-size: 46dp;
  hint-color: #818285;
  background-color: #FFFFFF00;
  transition: all 0.125s;
}

.screen TextInput.input:focus {
  background-color: #FFFFFF66;
  border-color: #796500;
}

.screen TextInput.input:hover {
  background-color: #FFFFFF66;
}

@media screen and (max-width: 1024px) {

.form .form_inputs {
  background-color: red;
}

}

完整的 CSS 规范可以在文档中找到：此处。

你也可以查看 eepp 中纯 CSS 主题的外观：此处。

实时演示（使用 emscripten）

由于 eepp 支持 emscripten，你可以快速浏览该库当前提供的一些示例、演示和工具。请注意，由于 emscripten 目前的局限性（无法访问文件系统、不支持自定义光标等），你会发现存在一些差异，并且演示并未针对大小进行优化，因此体积比预期要大。 注意：请使用具有良好 WebGL 和 WASM 支持的现代浏览器（Chrome/ium 70+ 或 Firefox 80+）。

• ecode - 代码编辑器

• UI 编辑器

• UI Hello World

• 纹理图集编辑器

• 地图编辑器

• 字体示例

• 物理模块演示

• 精灵示例

• 完整测试

7GUIs 示例

7GUIs 被称为“GUI 编程基准测试”，用于比较不同的 GUI 库并探索每个库在 GUI 编程方面的方法。7GUIs 中提出的所有 7 个任务都已在 eepp 中实现。这些任务很好地代表了使用 eepp GUI 可以达到的效果，并且对于演示如何使用该库实现不同任务也非常有用。

7GUIs 由以下任务组成：

• 计数器：演示 和 代码实现。

• 温度转换器: 演示 和 代码实现.

• 航班预订器: 演示 和 代码实现.

• 计时器: 演示 和 代码实现.

• CRUD: 演示 和 代码实现.

• 圆形绘制器: 演示 和 代码实现.

• 单元格: 演示 和 代码实现.

如何构建

该库只有一个外部依赖。你只需要安装带有头文件的 SDL2 库。此外，还需要 premake5 或 premake4 来生成用于构建该库的 Makefile 或项目文件。我将假设你知道自己在做什么，并跳过基础部分。

注意：eepp 默认使用 mojoAL 作为 OpenAL 的替代方案。 OpenAL 可作为音频后端可选使用。如果你想使用它， 你可以选择启用它。要启用它并禁用 mojoAL 替代方案， 你需要在任何 premake 调用中添加参数 --without-mojoal （例如：premake5 --without-mojoal gmake ）。

GNU/Linux

在 Ubuntu 系统中，操作大致如下（你还需要 gcc，但它 反正会被安装）：

sudo apt-get install premake5 libsdl2-2.0-0 libsdl2-dev

克隆仓库并在仓库根目录中运行：

premake5 gmake

或者，如果您已安装 premake4，则可以运行：

premake4 gmake

然后只需构建该库：

如果使用了 premake4：

make -C make/linux config=release（调试构建使用 config=debug）

如果使用了 premake5：

make -C make/linux config=release_x86_64（调试构建使用 debug_x86_64，或从 arm64 构建时使用 release_arm64/debug_arm64）

就这样。这将构建整个项目。

Windows

你有两个选择：使用 Visual Studio 或使用 MinGW。 要能够使用这些选项中的任意一个来构建项目，首先需要 使用 premake4 或 premake5 生成项目文件。 然后你需要将二进制文件添加到 PATH 中定义的任何可执行路径中 （或添加一个，或从本地路径使用）。

根据你的需求下载 Visual Studio 或 MinGW 文件。

Visual Studio

你需要使用 premake5 并运行：

premake5.exe --windows-vc-build vs2022

然后项目文件应在 make/windows/ 中找到。完整的解决方案 以及所有项目都将可用。安装完所有内容后，您将能够 像其他任何项目一样构建 Visual Studio 解决方案。

使用命令行参数 --windows-vc-build 将自动下载 SDL2 依赖项 并将路径添加到构建过程中，以便对其进行链接，而无需手动下载任何 外部依赖项。

然后只需在 Visual Studio 中构建解决方案，或在控制台中手动运行 MSBuild：

"%MSBUILD_PATH%\MSBuild.exe" .\make\windows\eepp.sln -m

其中 %MSBUILD_PATH% 是 MSBuild.exe 的 Visual Studio 路径，例如对于 VS2022 Community Edition，该路径通常为：

C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\

MinGW

Windows MinGW 构建正在使用 w64devkit 发行版进行生成和测试。 由于构建过程中发现的一些问题，MSYS 目前未获得官方支持（但通过一些额外步骤仍可进行构建）。

如果你正在使用 w64devkit，你需要 下载 并解压它，我们假设它已解压至 C:\w64devkit。

以管理员身份运行 C:\w64devkit\w64devkit.exe（right click -> Run as administrator ）。

然后进入 eepp 克隆的仓库目录并运行：

premake5.exe --windows-mingw-build gmake

--windows-mingw-build 将自动下载并链接外部依赖项（SDL2）。

然后只需使用 mingw32-make.exe 或任何等效工具构建位于 make/windows/ 中的项目：

mingw32-make.exe -C make\\windows config=release_x86_64

要构建调试版本，请运行：

mingw32-make.exe -C make\\windows config=debug_x86_64

然后确保将位于 src/thirdparty/SDL2-2.XX.X/x86_64-w64-mingw32/bin/SDL2.dll 的 SDL2.dll 文件复制到 bin。 如果由于某种原因 eepp.dll（或 eepp-debug.dll）未被自动复制，你可以将它们从 libs/windows/x86_64/ 复制到 bin。

macOS

你需要预编译的二进制文件和开发库 SDL2，OpenAL 已随操作系统提供。 安装 SDL2 框架后，你应该能够构建该项目。

你有两种构建项目的选项：使用 XCode 或使用 Makefiles。 要使用这两种选项中的任何一种进行构建，你首先需要 使用 premake4 或 premake5 构建项目文件。

Makefiles

使用 premake5

生成项目：

premake5 --use-frameworks gmake

然后构建它：

make -C make/macosx config=release_x86_64（或 config=debug_x86_64 用于调试构建，或 release_arm64/debug_arm64 如果从 arm64 构建）

使用 premake4

你可以使用 projects/osx/make.sh 脚本，该脚本会生成 Makefiles 并构建项目。

XCode

运行：

premake5 --use-frameworks xcode4

并打开在 make/macosx/ 处生成的 XCode 项目，或者简单地通过命令行构建：

xcodebuild -project make/macosx/project-name.xcodeproj

Android

projects/android-project/ 中有一个 gradle 项目。它将构建包含所有依赖项的库。请使用示例项目作为您项目的基础。请注意，有一个 eepp.mk 项目文件用于构建该库。该文件可用于您的项目中。

iOS

该项目提供了两个文件来构建库和演示。您可以根据需要选择使用其中任何一个。 这些文件位于 projects/ios：

gen-xcode4-proj.sh 脚本

此脚本可用于生成 eepp 中包含的所有项目（演示、工具、共享库、静态库等）的 xcode 项目和解决方案。它还会下载并构建 SDL2 fat 静态库，以便能够在项目中引用该库。构建项目后，遗憾的是，您需要对想要构建或测试的任何/所有项目进行一些小的更改，因为生成的项目缺少一些小的配置。运行此脚本后，您需要打开位于 make/ios/eepp.xcworkspace 的解决方案。构建静态库时不会遇到任何问题（开箱即用）。但要测试某些示例，需要：

添加 Info.plist 文件

选择（点击项目名称）你要测试的项目，例如 eepp-empty-window。你会看到几个标签/选项，转到 Build Settings， 找到 Info.plist 文件选项，双击进行编辑并写入： Info.plist。这将指示读取位于与项目相同 目录中的该文件。然后转到 General 标签，并填写 Bundle Identifier，使用将要生成的应用包标识符名称， 对于此示例，你可以使用类似以下内容： eepp-empty-window。 这将允许你构建并运行该项目。

向项目添加资源

此 eepp-empty-window 演示不使用任何资源/素材，但其他演示 将需要加载资源，并且这些资源需要添加到项目中，以便 对应用包可用。例如，项目 eepp-ui-hello-world， 将要求你将 assets 文件夹添加到项目中。你需要做的是： 选择项目并转到 Build Phases 标签，在 Copy Bundles Resources 中点击加号图标（+），然后转到 Add Other... 并定位并选择 bin/assets/ 文件夹，然后 Finish。这样就足够了。

compile-all.sh 脚本

此脚本可用于将 SDL2 和 eepp 构建为两个包含 arm64 和 x86_64 架构的胖静态库 （arm64 用于 iPhone/iPad，x86_64 用于 模拟器）。要生成发布版构建，请将 config=release_arm64 作为参数 传递给脚本（sh compile-all.sh config=release_arm64）。构建的文件将 位于 libs/ios/，分别为 libSDL2.a 和 libeepp.a（或 libeepp-debug.a 用于 调试版构建）。这两个文件可以集成到您的项目中。

emscripten

您首先需要 下载并安装 emscripten。 然后在 projects/emscripten/make.sh 中有一个用于构建 emscripten 项目的脚本。在运行此脚本之前，请记住设置 emsdk 环境，它应该类似于：source /path/to/emsdk/emsdk_env.sh。 在 GNU/Linux 或 macOS 上这应该就足够了（仅在 GNU/Linux 上测试过）。

如何运行演示和工具？

构建完成后，所有二进制文件都位于 bin 目录中。这些二进制文件需要两个文件： eepp 库和 SDL2 库。eepp 库将位于 libs/{OS}/。构建 脚本会尝试将 eepp 库符号链接到 bin，如果失败，则应手动 复制或符号链接。至于 SDL2 库，仓库中未提供，因此为了运行 演示，您需要下载正确操作系统版本和架构的 SDL2 库。

作者评论

该库已经开发了好几年，自其诞生以来经历了诸多变化，我会进行我认为必要的任何更改以改进它，因此 API 尚未完全稳定（但已接近稳定）。 它被用于多个主要面向 Android 设备和 Windows PC 开发的应用程序，这些应用程序大多用于广告宣传活动。

我个人从未有时间使用它来开发一个复杂的库游戏（几个令人沮丧的项目），但我为客户制作了几个面向 UI 的游戏。

当前项目的重点是 UI 模块。我将继续专注于此方面开展工作。

计划是提供一个完全硬件加速的替代 UI 工具包，类似于 Android 工具包但更简单（即易于使用），并且也面向桌面应用程序。

音频和网络模块基于 SFML 中的模块，并存在上述的几个重要差异。

我喜欢使用那些做得好且符合我需求的东西，但由于我对如何实现某些事物有个人看法，我更喜欢获取代码，以便对其拥有完全的控制权。

此外，许多想法来自/正来自其他项目。我能想到的一些包括： cocos2d-x、raylib、Android SDK、libGDX、Godot、XNA、LÖVE，以及许多 其他项目。

如果出于某种疯狂的原因，这一切听起来对你很有趣，请联系我，告诉我我是否能帮助你进入这个库，也许如果你愿意，你将来也可以为它做出贡献。这个项目最需要的是贡献者。

该库目前的状态还不错。就功能而言，它应该与市面上最常用的 2D 游戏引擎处于相似的地位。但当然，它缺乏像 Godot 或 cocos2d-x 那样所能提供的支持+社区，仅举两例。

该库的主要理念是专注于一种更好的通用方法，用于开发重度依赖 UI 的应用和游戏，相比其他选项，拥有更简洁的代码和实现。

我开发这个库的主要原因是为了_乐趣_和_学习_新技术。我喜欢花时间在这个库上工作，但我知道，鉴于有如此众多的类似替代品，开发这样的东西可能并没有真正的理由。

关于代码质量：这个项目开始于很久以前，并且随着时间推移经历了许多修改。代码库中相当大的一部分仍然使用旧的 C++ 实践（例如：原始指针、自实现的线程、互斥锁等）。其中一些东西可以“现代化”，但其他一些则没有太大意义，或者对其进行彻底改造所花费的时间不足以证明其价值。我正在“现代化”代码的某些部分，而新代码通常看起来更现代。

未来的计划/想法

持续改进 UI 系统，添加新的控件和布局，并改进 CSS 支持。

简化和改进 UI 控件的皮肤/主题支持。

改进/创建 UI 模块的文档。

添加更多示例和一些工具。

添加脚本支持，但我希望先稳定库，不过我正在朝这个方向努力。

添加 2D 骨骼动画支持（可能是 Spine2D，实现起来应该工作量不大）。

可能会弃用 Maps 模块，因为我将把精力集中在 UI 系统上。

致谢

特别感谢

• Sean Barrett 提供了 stb_image 和所有 stb 库。

• Sam Latinga 提供了 Simple DirectMedia Layer。

• Jonathan Dummer 提供了 Simple OpenGL Image Library。

• Laurent Gomila 提供了 SFML

• Yuri Kobets 提供了 litehtml

• Michael R. P. Ragazzon 提供了 RmlUI

• rxi 提供了 lite

• Andreas Kling 提供了 SerenityOS

• Ryan C. Gordon 提供了 mojoAL

• David Reid 提供了 dr_libs

• Lion (Lieff) 提供了 minimp3 以及其他

• Lewis Van Winkle 提供了 PlusCallback

• Dieter Baron 和 Thomas Klausner 提供了 libzip

• Jean-loup Gailly 和 Mark Adler 提供了 zlib

• Milan Ikits 和 Marcelo Magallon 提供了 GLEW

• Mikko Mononen 提供了 nanosvg

• Scott Lembcke 提供了 Chipmunk2D

• Christophe Riccio 提供了 glm

• Rich Geldreich 提供了 imageresampler 和 jpeg-compressor

• Arseny Kapoulkine 提供了 pugixml

• Jason Perkins 提供了 premake

• Martín Lucas Golini（我）以及众多 SOIL2 和 efsw 的贡献者

• Xiph 开源社区，感谢 libogg 和 libvorbis

• ARMmbed 社区，感谢 mbed TLS

• kcat，感谢 openal-soft

• FreeType Project

• 以及许多其他人！

代码许可证

MIT License