Skip to content

feat: add lua_list_characters and lua_import_character #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mcagnion wants to merge 4 commits into from
Closed

feat: add lua_list_characters and lua_import_character #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8018a04
fix(tests): align mock response keys with bridge handler shape
mcagnion Apr 25, 2026
4990121
feat: add lua_list_characters and lua_import_character with PoE API i…
mcagnion Apr 25, 2026
8663aac
docs: point users to ianderse/dev branch instead of stale api-stdio
mcagnion Apr 25, 2026
a2d2235
fix: allow POE_ACCOUNT_NAME for character import
mcagnion Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ npm run build
| `POB_CMD` | `luajit` | LuaJIT binary path |
| `POB_TIMEOUT_MS` | `10000` | Lua request timeout (ms) |
| `POE_TRADE_ENABLED` | `false` | Enable Trade API tools |
| `POE_SESSION_ID` | (none) | POESESSID cookie value, used for fetching private PoE profiles via `lua_import_character` / `lua_list_characters`. **Sensitive** — treat like a password; do not commit or share. |

### Setting Up the Lua Bridge

Expand All @@ -154,10 +155,12 @@ sudo apt-get install luajit
```bash
git clone https://github.com/ianderse/PathOfBuilding.git
cd PathOfBuilding
git checkout api-stdio
git checkout dev
```
Note the full path to the `src/` directory — that's your `POB_FORK_PATH`.

> **Note**: the JSON-RPC API now lives on the `dev` branch (the head of upstream PR [PathOfBuildingCommunity/PathOfBuilding#9505](https://github.com/PathOfBuildingCommunity/PathOfBuilding/pull/9505)), kept in sync with `PathOfBuildingCommunity/dev`. The older `api-stdio` branch is stale and missing recent tree-version data — using it will crash on `lua_load_build` for current-league builds.

#### 3. Verify
```bash
luajit -v
Expand All @@ -166,11 +169,29 @@ ls /path/to/PathOfBuilding/src/HeadlessWrapper.lua

#### 4. Update Claude Desktop config and restart Claude Desktop

### Importing a Live Character from PoE

You can import any of your live characters directly from the official Path of Exile API into the loaded build — tree, jewels, items, and skill gems are pulled from the game and applied:

```
1. lua_start
2. lua_list_characters (account_name: "YourName#1234")
3. lua_new_build (or lua_load_build for an existing template)
4. lua_import_character (account_name: "YourName#1234", character_name: "MyChar")
5. lua_save_build (build_name: "MyChar.xml")
```

`lua_import_character` returns a before/after diff so you can see exactly what changed (stats, items per slot, skill groups, tree node count). The active spec, items, and gems are **replaced**; build notes, configuration, other specs, and other item sets are **preserved**.

**Weapon swap behavior**: by default, the import places the in-game active weapons in the primary slots and forces PoB's calc engine to use those primary slots (so PoB stats match what you actually wear in game). If you maintain a custom swap configuration in PoB (e.g. leveling weapons stored in the swap slots) and want it preserved, pass `ignore_weapon_swap: true` — that skips the swap-slot import AND leaves your existing weapon-set toggle untouched.

For **private profiles** (the PoE default), set `POE_SESSION_ID` to your `POESESSID` cookie value (32 hex chars from `pathofexile.com` cookies). Treat it like a password — never commit it. Public profiles do not need this.

---

## Available Tools

The server registers **91 tools** across 10 categories.
The server registers **93 tools** across 10 categories.

### XML-Based Tools (Always Available)

Expand Down Expand Up @@ -223,6 +244,8 @@ The server registers **91 tools** across 10 categories.
| `list_item_sets` | List all item sets in the current build |
| `select_item_set` | Switch active item set |
| `plan_leveling` | Generate a leveling plan for a build |
| `lua_list_characters` | List characters on a PoE account via the official API (sorted by last login) |
| `lua_import_character` | Import a live character (tree/jewels/items/gems) into the loaded build with a before/after diff |

**`lua_set_tree` class IDs**: 0=Scion, 1=Marauder, 2=Ranger, 3=Witch, 4=Duelist, 5=Templar, 6=Shadow

Expand Down
Loading