Path of Building Community SimpleGraphic.dll

macOS port: this fork (pathanin/PathOfBuilding-SimpleGraphic) adds a native arm64 macOS build on top of the upstream Windows-only project, for use with pathanin/PathOfBuilding-PoE2. It is not part of the official/upstream project. See Building on macOS below; everything else in this document describes the original Windows-targeted DLL and still applies unchanged.

Introduction

SimpleGraphic.dll is the host environment for Lua. It contains the API used by the application's Lua logic, as well as a 2D OpenGL ES 2.0 renderer, window management, input handling, and a debug console. It exports one symbol, RunLuaFileAsWin, which is passed a C-style argc/argv argument list, with the script path as argv[0].

The Windows-specific code is contained in 5 files:

• win\entry.cpp: Contains the DLL export It just creates the system main module, and runs it
• engine\system\win\sys_main.cpp: The system main module. It initialises the application, and contains generic OS interface functions, such as input and clipboard handling
• engine\system\win\sys_console.cpp: Manages the debug console window that appears during the program's initialisation
• engine\system\win\sys_video.cpp: Creates and manages the main program window
• engine\system\win\sys_opengl.cpp: Initialises OpenGL

Building

SimpleGraphic.dll is currently built using Visual Studio 2022 for 64-bit.

The DLL depends on a number of 3rd-party libraries, all provided either as direct submodules and built by the main CMakeLists.txt file or built from ports in the vcpkg submodule as part of the build process.

The build process will also build the lcurl and lzip Lua extensions against the same LuaJIT version as the DLL is built with.

A short guide on building and debugging the DLL is available in CONTRIBUTING.md.

The INSTALL target will deploy the DLL, its dependencies and the VC++ runtime to the installation directory.

Building on macOS

This fork adds a native arm64 macOS build, used as a drop-in replacement for the Windows DLL + PathOfBuilding.exe when running PathOfBuilding-PoE2 on Apple Silicon. It's a personal/community port, not an officially supported target.

What's different from the upstream Windows build:

• engine/system/win/sys_video.cpp requests ANGLE's Metal backend on __APPLE__ instead of the legacy desktop-OpenGL fallback (the two are mutually exclusive in ANGLE's own macOS build, so this requires the metal vcpkg feature for the osx platform in vcpkg.json).
• engine/system/win/sys_main.cpp maps GLFW_KEY_LEFT_SUPER/RIGHT_SUPER (Cmd) to KEY_CTRL, so the Lua UI's Ctrl-based shortcuts (copy/paste, undo, select-all, tree zoom, etc.) respond to Cmd, the Mac convention. Physical Ctrl still works.
• Various portability fixes for building under Clang/libc++ rather than MSVC (missing includes, a std::min template-deduction fix, Sleep() replaced with std::this_thread::sleep_for, LuaJIT's vcpkg port patched for a null-safe getenv, CMake's platform-conditional sources fixed so Windows-only libs/sources aren't pulled in on other platforms).
• macos-launcher/pob_launch.c: a small native launcher that replaces PathOfBuilding-PoE2.exe. It dlopens libSimpleGraphic.dylib from its own directory and calls the same RunLuaFileAsWin entry point, with the script path as argv[0]. It also re-execs itself once with DYLD_LIBRARY_PATH set so GLFW's dlopen("libEGL.dylib") can find the ANGLE dylibs alongside it, and points LUA_PATH/LUA_CPATH at exe-relative paths (Unix LuaJIT has no equivalent of Windows' !\lua\?.lua exe-relative default).

Build steps:

cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DVCPKG_TARGET_TRIPLET=arm64-osx-dynamic -DVCPKG_HOST_TRIPLET=arm64-osx-dynamic \
  -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake   # host triplet must match target
cmake --build build
clang -O2 -o macos-launcher/pob-poe2 -Wl,-rpath,@loader_path macos-launcher/pob_launch.c

# Stage the outputs into the PathOfBuilding-PoE2 checkout's runtime/ directory:
cp build/libSimpleGraphic.dylib macos-launcher/pob-poe2 <path-to-PathOfBuilding-PoE2>/runtime/
# Native Lua modules go in renamed to .so:
#   liblcurl.dylib     -> lcurl.so
#   liblzip.dylib       -> lzip.so
#   liblua-utf8.dylib   -> lua-utf8.so
#   libsocket.dylib     -> socket.so
# Re-run `install_name_tool -add_rpath @loader_path` on any replaced dylib/so files.

Then run <path-to-PathOfBuilding-PoE2>/runtime/pob-poe2 in place of the Windows executable.

Debugging

Since SimpleGraphic.dll is dynamically loaded by PathOfBuilding.exe, to debug it, run PathOfBuilding.exe and then attach to that process using the "Debug" > "Attach to Process..." menu option in Visual Studio.

Visual Studio can also be configured to start the Path of Building executable when debugging a target which troubleshooting of early startup.

Project dependencies

Runtime and utilities:

• LuaJIT - fast Lua fork with JIT compilation that has diverged from upstream Lua at version 5.1
• curl - very common HTTP library, exposed to Lua
• fmtlib - modern string formatting
• libsodium - friendly cryptographic primitives, used in SimpleGraphic for fast hashing
• pkgconf - part of the build process to locate builds of bundled libraries
• re2 - regex library

Graphics:

• GLFW - multi-platform windowing library for OpenGL (and other APIs)
• ANGLE - OpenGL ES runtime from Google built on top of native rendering APIs
• Glad 2 - OpenGL header generator

Compression and image formats:

• stb - single-header libraries for many things, here image reading and writing
• giflib - GIF loading/saving
• libjpeg-turbo - JPEG loading/saving
• libpng - PNG loading/saving
• liblzma - LZMA compression/decompression
• zlib - zlib compression/decompression

Licence

MIT

For 3rd-party licences, see LICENSE. The licencing information is considered to be part of the documentation.