The project repository is LocalExile/evryBuild.
Report bugs and feature suggestions in its issue tracker,
and submit pull requests against master.
For this fork's external SQLite integration, start with setup and compatibility,
validation and local packaging.
The integration lives in src/Modules/LocalExile.lua, src/Modules/LocalExileNative.lua and
tools/LocalExile.Export/; it must work with unmodified LocalExile, without a server API or network calls.
Keep loadable items/gems/passives even when gameplay support is missing, and report encoding omissions explicitly.
Compatibility rules belong to tools/LocalExile.Export/compatibility.json: mark unverified mechanics unknown,
and attach evidence to new implemented/partial/unimplemented rules.
The planner development notes below are adapted from upstream. evryBuild disables application networking; use local XML files and pasted build codes when reproducing issues. For an evryBuild bug report, provide reproduction steps and a saved XML or pasted build code with private details removed.
- Reporting bugs
- Requesting features
- Contributing code
- Setting up a development installation
- Setting up a development environment
- Keeping your fork up to date
- Path of Building development tutorials
- Exporting GGPK data from Path of Exile
- Using the inbuilt profiler
- Check the evryBuild issue tracker for an existing report.
- Check the latest portable release and include the version you tested. Automatic update checks are disabled.
- If you've found an issue with offence or defence calculations, make sure you check the breakdown for that calculation in the Calcs tab to see how it is being performed, as this may help you find the cause.
- Select the "Bug Report" issue template and fill out all fields.
- Please provide detailed instructions on how to reproduce the bug, if possible.
- Provide a saved XML file or pasted build code for a build that is affected by the bug, if possible. In the "Import/Export Build" tab, click "Generate" and copy the code into your report. Online sharing is disabled.
Build share codes allow us to reproduce bugs much more quickly.
Feature requests are always welcome. Note that not all requests will receive an immediate response.
- Check the evryBuild issue tracker for related requests.
- Read the latest release notes, as the feature may already have been added.
- Select the "Feature Request" issue template and fill out all fields.
- Be specific! The more details, the better.
- Small requests are fine, even if it's just adding support for a minor modifier on a rarely-used unique.
- Familiarise yourself with the code base here to get you started.
- Use evryBuild issues to discuss changes with the LocalExile maintainers.
- Create pull requests against
masterin LocalExile/evryBuild. - Make sure that the changes have been thoroughly tested!
- If you're updating mod parsing logic, make sure to reload PoB with
Ctrl+F5to regenerate./src/Data/ModCache.lua. This is a very large, automatically generated file that can be used to verify your changes didn't affect any other mods inadvertently. Make sure to commit./src/Data/ModCache.luaif your changes cause it to differ. - There are many more files in the
./src/Datadirectory that are automatically generated. This is indicated by the header-- This file is automatically generated, do not edit!. To change these, instead change the scripts in the./src/Exportdirectory and rerun the exporter. For your PR, please include all relevant changes to both the scripts and data files.
Note: This tutorial assumes that you are already familiar with Git.
The easiest way to make and test changes is by setting up a development installation, in which the program runs directly from a local copy of the repository:
-
Clone the repository using this command:
git clone https://github.com/LocalExile/evryBuild.git -
Go to the folder where you cloned evryBuild (for example,
C:/src/evryBuild).cd evryBuild -
Build the bundled exporter and launch the planner in PowerShell:
.\scripts\build-exporter.ps1 & '.\runtime\Path{space}of{space}Building.exe'
See RELEASE.md for the Windows build requirements and portable packaging instructions. You can now use the shortcut to run the program from the repository. Running the program in this manner automatically enables "Dev Mode", which has some handy debugging feature:
F5restarts the program in-place (this is what usually happens when an update is applied).Ctrl+~toggles the console (Note that this does not work with all keyboard layouts. US layout is a safe bet though).ConPrintf()can be used to output to the console. Search for "===" in the project files if you want to get rid of the default debugging strings.- Holding
Altadds additional debugging information to tooltips:- Items and passives show all internal modifiers that they are granting.
- Stats that aren't parsed correctly will show any unrecognised parts of the stat description.
- Passives also show node ID and node power values.
- Conditional options in the Configuration tab show the list of dependent modifiers.
- While in the Tree tab, holding
Altalso highlights nodes that have unrecognised modifiers. - Holding
Ctrlwhile launching the program will rebuild the mod cache.
Note that automatic updates are disabled in Dev Mode.
Automatic updates and online installers are disabled in every evryBuild mode. Use the current portable release to update an installed copy. Changing development-mode flags does not enable network access.
The evryBuild origin is https://github.com/LocalExile/evryBuild.git, and its default branch is master.
For a clean checkout with no local changes, run these commands in PowerShell from the repository root:
git switch master
git pull --ff-only origin masterIf Git reports local changes or divergent history, preserve that work and review it before merging. Planner upstream remains PathOfBuildingCommunity/PathOfBuilding. Port upstream planner changes on a separate branch and run the evryBuild validation checks before merging; retain the external SQLite exporter and offline application policy.
Note: This tutorial assumes that you are already familiar with the development tool of your choice.
If you want to use a text editor, Visual Studio Code (proprietary) is recommended. If you want to use an IDE instead, PyCharm Community or IntelliJ Idea Community (open source) are recommended. They are all free and support EmmyLua, a Lua plugin that comes with a language server, debugger and many pleasant features. It is recommended to use it over the built-in Lua plugins.
Please note that EmmyLua is not available for other editors based on Visual Studio Code, such as VSCodium or Eclipse Theia but can be built from source if needed.
-
Create a new Debug Configuration of type EmmyLua New Debug
-
Open
./src/Launch.lua -
Click the beginning of the line directly after
function launch:OnInit() -
Insert the debugger code:
Automatically:
- Open the Command Palette (F1)
- Type EmmyLua: Insert Emmy Debugger Code
- Choose
x64from the drop-down list
Or manually:
- Open the Visual Studio Code extensions folder. On Windows, this defaults to
%USERPROFILE%/.vscode/extensions - Find the sub-folder that contains
emmy_core.dll. You should find both x86 and x64; pick x64. For example,C:/Users/someuser/.vscode/extensions/tangzx.emmylua-0.9.22-win32-x64/debugger/emmy/windows/x64. Uses this in the snippet below. Note the version number will change with every update. - Copy-paste the following code snippet:
-- Path to emmy_core.dll. You will need to update it to point to the EmmyLua dlls in YOUR installation. -- Note the "?.dll" at the end of the path is mandatory. package.cpath = package.cpath .. ";C:/Users/someuser/.vscode/extensions/tangzx.emmylua-0.5.19/debugger/emmy/windows/x64/?.dll" local dbg = require("emmy_core") -- This port must match the IDE configuration. Default is 9966. dbg.tcpListen("localhost", 9966) --dbg.waitIDE() -- Uncomment this line if you want PoB to wait until the debugger is attached.
-
Set breakpoints in the source with VSCode's built-in breakpoint system (or use a non-local
dbgand call_G.dbg.breakHere()) -
Click the Run and Debug icon on the Activity Bar
-
Make sure EmmyLua New Debug is selected in the "Run and Debug" dropdown
-
Start your modified Path of Building Community
-
In VSCode click Start Debugging (the green icon) or press F5
-
The debugger should connect
Depending on the amount of system ram you have available and the amount that gets assigned to the jvm running the emmylua language server you might run into issues when trying to debug Path of building.
Files in /Data /Export and /TreeData can be massive and cause the EmmyLua language server to use a significant amount of memory. Sometimes causing the language server to crash. To avoid this and speed up initialization consider adding an .emmyrc.json file to the .vscode folder in the root of the Path of building folder with the following content:
{
"$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
"runtime": {
"version": "LuaJIT"
},
"workspace": {
"ignoreGlobs": [
"**/src/Data/**/*.lua",
"**/src/TreeData/**/*.lua",
"**/src/Modules/ModParser.lua"
]
}
}- Create a new "Debug Configuration" of type "Emmy Debugger(NEW)".
- Select "x64" version.
- Select if you want the program to block (checkbox) until you attached the debugger (useful if you have to debug the startup process).
- Copy the generated code snippet directly below
function launch:OnInit()in./src/Launch.lua. - Start Path of Building Community
- Attach the debugger
If you're on windows, consider downloading git for windows and installing git bash. Git bash comes with a variety of typical linux tools such as grep that can make navigating the code base much easier.
If you're using linux you can run the ./runtime/Path{space}of{space}Building.exe executable with wine. You will need to provide a valid wine path to the emmy lua debugger directory.
# winepath -w ~/.vscode/extensions/tangzx.emmylua-0.8.20-linux-x64/debugger/emmy/windows/x64/
Z:\home\dev\.vscode\extensions\tangzx.emmylua-0.8.20-linux-x64\debugger\emmy\windows\x64\PoB uses the Busted framework to run its tests. Tests are stored under spec/System and run automatically when a PR is modified.
More tests can be added to this folder to test specific functionality, or new test builds can be added to ensure nothing changed that wasn't intended.
- Install Docker
- Run
docker-compose upfrom the command line - Review the results in the terminal
Please try to include tests for your new features in your pull request. Additionally, if your pr breaks a test that should be passing please update it accordingly.
When running tests with a docker container it is possible to use EmmyLua for debugging. Paste in the following right under function launch:OnInit() in ./src/Launch.lua:
package.cpath = package.cpath .. ";/usr/local/bin/?.so"
local dbg = require("emmy_core")
-- This port must match the IDE Code configuration. Default is 9966.
dbg.tcpListen("localhost", 9966)
dbg.waitIDE()After running docker-compose up the code will wait at the dbg.waitIDE() line until a debugger is attached. This will allow stepping through any code that is internal to POB but will not work for busted related code. Note that this only works for unit tests described above.
Warning
This will not work on files from the torrent that is released before league launches, as it contains no Data section.
Note: This tutorial assumes that you are already familiar with the GGPK and its structure. poe-tool-dev/ggpk.discussion is a good starting point.
The ./src/Data folder contains generated files which are created using the scripts in the ./src/Export/Scripts folder based on Path of Exile game data.
If you change any logic/configuration in ./src/Export, you will need to regenerate the appropriate ./src/Data files. You can do so by running the ./src/Export scripts using the .dat viewer at ./src/Export/Launch.lua:
Tip
Binaries are usually available at https://github.com/zao/ooz/releases.
Note: For this tutorial, you will need a working installation of Visual Studio Community as well as some familiarity with build tools such as CMake.
-
In Visual Studio, clone the following repository using this command:
git clone --recurse-submodules -b master https://github.com/zao/ooz -
Configure CMake.
-
Build
bun_extract_file.exe,libbun.dllandlibooz.dll.
-
Copy
bun_extract_file.exe,libbun.dllandlibooz.dllto.\src\Export\ggpk\. -
Create a shortcut to
.\runtime\Path{space}of{space}Building.exewith the path to.\src\Export\Launch.luaas the first argument. You should end up with something like:"<path to repo>\runtime\Path{space}of{space}Building.exe" "<path to repo>\src\Export\Launch.lua" -
Run the shortcut. "Dat View", the GGPK data viewer UI, should appear. If you get an error, be sure you're using the latest release of Path of Building Community.
-
Click
Edit Sources...to display the "New DAT Source" popup. ClickNewand enter a name. -
Paste the full path to
Content.ggpkinto the "Source from GGPK/Steam PoE path" box and hitEnter. For the stand-alone client, the path must include the file-name. (Do not put anything in the "Source from DAT files" box unless you have already manually unpacked the relevant files.)Example input for the stand-alone client:
C:\Path of Exile\Content.ggpkExample input for Steam:
C:\Program Files (x86)\Steam\steamapps\common\Path of ExileIf successful, you should see some cmd windows pop up as the files are unpacked, and then a list of the data tables in the GGPK file should appear.
-
Click
Scripts >>to show the list of available export scripts. Double-clicking a script will run it, and the box to the right will show any output from the script. -
If you run into any errors, update the code in
./src/Exportas necessary and try again.
The profiler is found at https://github.com/charlesmallah/lua-profiler and is written entirely in lua under a MIT license.
Pressing pause will start and stop the profiler depending upon if profiling is active. This isn't very precise and has very wide scope so if you want to profile a certain section of code you can also call profiler.start() and profiler.stop() at the start and end of code block you want to profile. Then calling profile.report(fileName) will generate a file in the src folder with the profiling data. This file is called the name given to function or if none are given it is called "profiler.log".
This file contains:
- Total time spent executing
- A table containing information about the profiling
- File, function and line are the file that a given function was executed in and the line of the function definition
- Time and % are the time spent executing code within a function and its percentage relative to the total time spent
- # Is the number of times the function was called
- ~ is displayed if function execution time is less than 0.0001
Here is an example table that could be generated
> Total time: 0.510000 s
-------------------------------------------------------------------------------------------------------------------------------------
| FILE : FUNCTION : LINE : TIME : % : # |
-------------------------------------------------------------------------------------------------------------------------------------
| ...ers\*****\Documents\GitHub\: Anon : 104 : 0.4770 : 93.5 : 2 |
| Modules/Main : Anon : 263 : 0.4770 : 93.5 : 2 |
| Modules/Build : CallMode : 906 : 0.4730 : 92.7 : 2 |
| Classes/TreeTab : Draw : 178 : 0.4360 : 85.5 : 2 |
| Classes/PassiveTreeView : Draw : 97 : 0.4240 : 83.1 : 2 |
| Classes/Control : IsMouseInBounds : 91 : 0.4150 : 81.4 : 5 |
| Classes/Control : GetProperty : 83 : 0.4080 : 80.0 : 26 |
| Classes/PassiveTreeView : renderConnector : 378 : 0.2400 : 47.1 : 5256 |
| Classes/PassiveTreeView : DrawAsset : 751 : 0.0720 : 14.1 : 9532 |
| Classes/PassiveTreeView : treeToScreen : 178 : 0.0550 : 10.8 : 27020 |
| Classes/ControlHost : DrawControls : 85 : 0.0260 : 5.1 : 12 |
| Classes/Control : GetSize : 79 : 0.0230 : 4.5 : 1624 |
| Classes/PassiveTreeView : setConnectorColor : 363 : 0.0210 : 4.1 : 5884 |
| Classes/PassiveTreeView : renderGroup : 333 : 0.0160 : 3.1 : 1222 |
| Classes/Control : IsShown : 83 : 0.0120 : 2.4 : 201 |
| Classes/PassiveTreeView : getState : 366 : 0.0100 : 2.0 : 5256 |
| Classes/ControlHost : ProcessControlsInput : 32 : 0.0100 : 2.0 : 6 |
| Classes/ControlHost : GetMouseOverControl : 24 : 0.0090 : 1.8 : 22 |
| Classes/Control : GetProperty : 34 : 0.0070 : 1.4 : 3794 |
| Classes/EditControl : IsMouseOver : 114 : 0.0060 : 1.2 : 8 |
| Classes/DropDownControl : IsMouseOver : 160 : 0.0050 : 1.0 : 18 |
| Classes/CheckBoxControl : IsMouseOver : 14 : 0.0030 : 0.6 : 6 |
| Classes/ScrollBarControl : IsMouseOver : 70 : 0.0030 : 0.6 : 27 |
| Modules/Build : GetProperty : 141 : 0.0020 : 0.4 : 99 |
| Classes/DropDownControl : CheckDroppedWidth : 467 : 0.0020 : 0.4 : 10 |
| Modules/Common : __index : 77 : 0.0010 : 0.2 : 306 |
| Modules/Build : GetProperty : 596 : 0.0010 : 0.2 : 18 |
| Classes/TextListControl : IsMouseOver : 18 : 0.0010 : 0.2 : 1 |
-------------------------------------------------------------------------------------------------------------------------------------
| Modules/Main : GetProperty : 111 : ~ : ~ : 16 |
| Classes/TextListControl : GetProperty : 10 : ~ : ~ : 10 |
| Classes/PassiveSpec : CountAllocNodes : 468 : ~ : ~ : 99 |
| Modules/Build : GetProperty : 133 : ~ : ~ : 33 |
| Modules/Build : GetProperty : 532 : ~ : ~ : 26 |
| Modules/Build : GetProperty : 499 : ~ : ~ : 2 |
| Classes/SearchHost : IsSearchActive : 68 : ~ : ~ : 32 |
| Classes/DropDownControl : GetDropCount : 92 : ~ : ~ : 16 |
| Modules/Main : DrawArrow : 921 : ~ : ~ : 12 |
| Modules/Build : GetProperty : 483 : ~ : ~ : 2 |
| Modules/Main : GetProperty : 154 : ~ : ~ : 3 |
| Modules/Main : Anon : 405 : ~ : ~ : 1 |
| Classes/TradeQuery : onFrameFunc : 42 : ~ : ~ : 2 |
| Classes/TradeQueryRequests : ProcessQueue : 21 : ~ : ~ : 2 |
| Classes/LabelControl : GetProperty : 9 : ~ : ~ : 37 |
| Modules/Main : GetProperty : 143 : ~ : ~ : 4 |
| Modules/Build : GetProperty : 503 : ~ : ~ : 2 |
| Modules/Main : GetProperty : 139 : ~ : ~ : 4 |
| Modules/Build : GetProperty : 544 : ~ : ~ : 26 |
| Modules/Build : GetProperty : 491 : ~ : ~ : 2 |
| ...ers\*****\Documents\GitHub\: Anon : 166 : ~ : ~ : 1 |
| Modules/Build : IsEnabled : 120 : ~ : ~ : 2 |
| Classes/EditControl : GetProperty : 62 : ~ : ~ : 84 |
| Modules/Build : GetProperty : 487 : ~ : ~ : 2 |
| Modules/Build : GetProperty : 495 : ~ : ~ : 2 |
| Modules/Build : GetProperty : 479 : ~ : ~ : 2 |
| Modules/Build : IsEnabled : 126 : ~ : ~ : 2 |
| Classes/ButtonControl : IsMouseOver : 30 : ~ : ~ : 64 |
| Classes/Control : SetAnchor : 42 : ~ : ~ : 2 |
| Classes/PassiveTreeView : screenToTree : 182 : ~ : ~ : 2 |
| Modules/Build : RefreshSkillSelectControls : 1174 : ~ : ~ : 2 |
| ...ers\*****\Documents\GitHub\: Anon : 134 : ~ : ~ : 1 |
| Modules/Common : wipeTable : 420 : ~ : ~ : 16 |
| Modules/Main : CallMode : 418 : ~ : ~ : 2 |
| Classes/DropDownControl : SelByValue : 122 : ~ : ~ : 2 |
| Classes/ItemsTab : GetSocketAndJewelForNodeID : 1248 : ~ : ~ : 84 |
| Classes/Control : IsEnabled : 34 : ~ : ~ : 54 |
| Classes/Control : IsEnabled : 87 : ~ : ~ : 54 |
| Classes/ScrollBarControl : SetContentDimension : 24 : ~ : ~ : 14 |
| Classes/EditControl : UpdateScrollBars : 201 : ~ : ~ : 4 |
| Classes/UndoHandler : ResetUndo : 19 : ~ : ~ : 2 |
| Classes/DropDownControl : SetList : 458 : ~ : ~ : 6 |
| Classes/EditControl : CreateUndoState : 737 : ~ : ~ : 2 |
| Classes/EditControl : SetText : 90 : ~ : ~ : 2 |
| Modules/Common : copyTable : 351 : ~ : ~ : 2 |
-------------------------------------------------------------------------------------------------------------------------------------