|
| 1 | +## Path of Building Design Overview from @Openarl |
| 2 | + |
| 3 | +It is split into 2 main components: the program, and the runtime. |
| 4 | + |
| 5 | +The program consists of the Lua scripts that comprise the application logic, as well as |
| 6 | +the data files that the application uses. These are the files that are in the GitHub |
| 7 | +repository. When performing a normal install of the application (non-standalone) these |
| 8 | +files end up in %ProgramData%\Path of Building. In theory, this part of the application |
| 9 | +should be fully portable. The application's entry module is Launch.lua, which contains error |
| 10 | +handling and update management code. The API is defined in SimpleGraphic\ui_api.cpp. It's |
| 11 | +not very well documented at the moment, but there's a summary of the functions at the top of |
| 12 | +that file. |
| 13 | + |
| 14 | +The runtime consists of the platform-specific binaries, including the Lua interpreter and |
| 15 | +the host environment, as well as a few libraries, and the data files for the host environment. |
| 16 | +In a normal install, these files go in Program Files\Path of Building. In the GitHub |
| 17 | +repository, the runtime files are packed into a zip file (runtime-win32.zip). |
| 18 | + |
| 19 | +The runtime contains the following binaries: |
| 20 | + |
| 21 | +### Path of Building.exe |
| 22 | +I haven't included the source for this, because franky it's very boring, |
| 23 | +and is almost entirely Windows-centric code. It takes a Lua script as an argument (or looks |
| 24 | +for 'Launch.lua' if one isn't provided) and checks the first line for a host environment |
| 25 | +specification. This design enables the .exe to function as a generic Lua host, but for |
| 26 | +Path of Building the only host actually used is SimpleGraphic.dll, so all it really does is |
| 27 | +load SimpleGraphic.dll and pass the path of the script to the "RunLuaFileAsWin" export. |
| 28 | + |
| 29 | +### SimpleGraphic.dll |
| 30 | +This is the Lua host environment. It contains the API used by the |
| 31 | +application's Lua logic, as well as a 2D OpenGL renderer, window management, input handling, |
| 32 | +and a debug console. It exports one symbol, RunLuaFileAsWin, which is passed a C-style argc/argv |
| 33 | +argument list, with the script path as argv[0]. The Windows-specific code is contained in 5 files: |
| 34 | +- win\entry.cpp: Contains the DLL export. It just creates the system main module, and runs it! |
| 35 | +- engine\system\win\sys_main.cpp: The system main module; it initialises the application, and |
| 36 | +contains generic OS interface functions, such as input and clipboard handling. |
| 37 | +- engine\system\win\sys_console.cpp: Manages the debug console window that appears during the |
| 38 | +program's initialisation. |
| 39 | +- engine\system\win\sys_video.cpp: Creates and manages the main program window. There's a lot of |
| 40 | +cruft relating to fullscreen mode which could be stripped out as Path of Building only operates |
| 41 | +in windowed mode. |
| 42 | +- engine\system\win\sys_opengl.cpp: Initialises OpenGL. |
| 43 | + |
| 44 | +The engine depends on a number of libraries, which are all fully portable: |
| 45 | + - LuaJIT 2.0.4: I use the third-party JIT for Lua: http://luajit.org/ |
| 46 | + - ZLib 1.2.8 |
| 47 | + - libjpeg 9a: http://ijg.org/ |
| 48 | + - libpng 1.6.12: http://libpng.org/pub/png/libpng.html |
| 49 | + - GIFLIB 5.1.1: http://giflib.sourceforge.net/ |
| 50 | + - LibTiFF: http://www.libtiff.org/ (Path of Building doesn't use TIFF images so you could |
| 51 | + cut this out if you wanted to) |
| 52 | + |
| 53 | +### lua51.dll |
| 54 | +This is the aforementioned LuaJIT interpreter. |
| 55 | + |
| 56 | +### libcurl.dll |
| 57 | +This is of course cURL, which the application uses for network interaction. |
| 58 | +The specific version used is 7.54.0, if that matters. |
| 59 | + |
| 60 | +### lcurl.dll |
| 61 | +A Lua binding for libcurl: https://github.com/Lua-cURL/Lua-cURLv3 |
| 62 | + |
| 63 | +### lzip.dll |
| 64 | +A simple library I created to allow Lua code to extract from .zip files. This is used |
| 65 | +by the updates system. The code is a bit odd as it's a stripped-down version of a ZIP-based |
| 66 | +virtual file system, but it should be portable as it is. It depends on LuaJIT and ZLib. |
| 67 | + |
| 68 | +### Update.exe |
| 69 | +This is used by the updates system to update the runtime binaries. It runs with |
| 70 | +administrator priviliges to comply with Windows' UAC; that shouldn't be required on other OSs. |
| 71 | +It contains a Lua interpreter which runs the script passed as the first argument. In practice, the |
| 72 | +only script it will run is UpdateApply.lua. To allow the LuaJIT binary to be updated, it uses a |
| 73 | +standard Lua interpreter (not the JIT) which is embedded in the executable. The script's |
| 74 | +environment consists of the standard Lua libaries, plus an extra API function 'SpawnProcess' that |
| 75 | +starts the given process and returns without waiting for the process to finish. It also lowers the |
| 76 | +execution level so that the new process doesn't run with administrator priviliges. UpdateApply.lua |
| 77 | +uses this to restart the main application after the runtime files have been updated. |
0 commit comments