Sharing Lua scripts and the web planner

Arcane is three pieces. Do not zip the git repo or the injected DLL into the script pack.

Piece	What the user gets	Needs
Host	Arcane inject (separate product)	Official Tibia client
Lua pack	Scripts dropped into Documents	Inject; overlay Open folder
Planner pack	SharpPlanner.exe plus static maps\ tiles (overlay Download Planner, or a zip)	Overlay Connect to Planner

Players do not install Node. Overlay Connect to Planner starts Documents\SharpTib\planner\SharpPlanner.exe if nothing is listening on the port, then attaches ws://127.0.0.1:<port>/sharp. Open Planner uses the system browser at http://127.0.0.1:<port>/. The host and the browser are started detached from the Tibia/Steam process tree, so Steam does not keep the non-Steam game "in game" after the client exits. Overlay Disconnect does not kill the host. Closing Tibia does: a host the overlay spawned exits when the game process is gone. Author npm run dev is not given a game PID and stays up.

Workspace (all Arcane files)

%USERPROFILE%\Documents\SharpTib is the only Arcane home (config, game.storage, logs, crashes, hunt plans, planner exe). Official Tibia assets stay under %LOCALAPPDATA%\Tibia\….

Documents\SharpTib\
├─ scripts\
├─ planner\              SharpPlanner.exe, www\, plans-v1.json, planner.log
├─ maps\                 client minimap (floors 0–7) + TibiaMaps fallback
├─ state\
├─ logs\
├─ crashes\
├─ map\
├─ config.json
└─ script_store.json

Author docs live on this site (/guides/), not in Documents.

Pack 1 — Lua

Source of truth: %USERPROFILE%\Documents\SharpTib\scripts

Suggested zip name: Arcane-Lua-2026-08-25.zip

SharpTib/
├─ README.txt          (copy the “User install” section below)
└─ scripts\
    ├─ 01_hello.lua … 27_orbwalker.lua
    ├─ ui_*.lua
    ├─ logging.lua
    ├─ sharpgfx.lua
    ├─ sdk\
    └─ farming\

Include

• All top-level *.lua modules you want users to load (01–27, ui_*, logging.lua, sharpgfx.lua).
• scripts\sdk\ (entire tree, including data\ and events\).
• scripts\farming\.
• Optional: scripts\.cursor\rules\ (authoring rules only). The host rewrites MCP json on inject.

Exclude

• scripts\store\ (that user’s Community Store installs)
• scripts\backups\
• scripts\scripts.7z, .migrated-from-appdata
• scripts\.cursor\mcp.json, .vscode\, .mcp.json, .codex\, .gemini\, .arcane\ (seeded per machine)
• Legacy %APPDATA%\SharpTibia leftovers (do not ship them)
• Native C++, DLLs, world.bin, offsets, credentials

User install

1. Inject a matching Arcane build.
2. Overlay → Scripts → Open folder (Documents\SharpTib\scripts).
3. Copy the zip’s scripts\ files into that folder. Do not nest a second scripts directory.
4. Overlay → Reload all. Leave Auto-run off until they trust the files.
5. The host will not overwrite existing .lua files; a stale sdk\ on disk wins. To force this revision, replace sdk\ as a whole.

Players can also install official modules from overlay Community Store (no zip). Pack 1 is for offline copies and the Lua SDK tree. Hunt zones / publish / start from the browser need Pack 2.

How-tos, API, changelog, and the SDK zip are on this site (guides, versions). Do not ship a second markdown copy of these pages.

Pack 2 — Sharp Planner (exe + map tiles)

Suggested zip name: Arcane-Planner-2026-08-26.zip (manual drop-in still works).

Default path: overlay Map tab Download Planner. Config Server GET /tibia/planner/manifest points at a Tigris zip of SharpPlanner.exe plus optional maps/client and maps/tibiamaps color tiles. Clicking the button downloads it into Documents\SharpTib\planner\ and writes map tiles into Documents\SharpTib\maps\ (it will not start a ~70 MB pull by itself). If Connect is on, or Sharp Planner is already running, the overlay stops Connect, closes that exe, then replaces it.

Authors / maintainers:

cd web/live-map
npm run pack:publish

That packs the exe, zips sibling Documents\SharpTib\maps color tiles (no TibiaMaps waypoint costs), then POST /tibia/planner/publish (needs TIBIA_SCRIPT_ADMIN_TOKEN). npm run pack is local-only.

Players can still unzip SharpPlanner.exe here:

Documents\SharpTib\planner\SharpPlanner.exe

and the static tiles here (if they are not using Download Planner):

Documents\SharpTib\maps\client\minimapDocuments\SharpTib\maps\tibiamaps\minimap

Runtime creates www\, plans-v1.json, and planner.log next to the exe. Catalogs come from Pack 1 (scripts\sdk\data). Planner map pixels come from those local files, not from the injected DLL. Live creatures stay overlay data.

User install

1. Overlay → Map tab. If the exe is missing (or outdated), click Download Planner, then wait for Installed. Enable Connect to Planner. A running planner is closed first so the file can be replaced. This overlay build is required to unpack the maps folder from the zip.
2. Port 38574. Enable Connect to Planner until it shows Connected ws://127.0.0.1:38574/sharp.
3. Open Planner (http://127.0.0.1:38574/ in the system browser). Floor 7 should match the official client extraction; underground floors use the TibiaMaps fallback.

If no release is published yet, the overlay still says Install Sharp Planner to Documents\SharpTib\planner.

Authors still use npm run dev / npm start in web/live-map (HTTP, same port).

If the planner is not running and Connect cannot start it, drawing/publishing new plans cannot work. Farming from an already-published plan in Lua can still work.

Two zips vs one

Audience	Give them
Run examples / farm	Pack 1 only + inject
Draw hunt zones and publish plans	Pack 1 + Pack 2 (the exe)
Write new Lua	Pack 1 + inject + open Documents\SharpTib\scripts as the IDE workspace

Do not point Config scripts_folder at a second copy of Pack 1. Documents wins and the extra copy goes stale.

Maintainer checklist before zipping Pack 1

• SDK scripts\sdk\VERSION matches what you claim (currently 2026.08.27-r2).
• 09_farm.lua header still uses sdk.kite / current farming modules.
• No personal CONFIG secrets, no live character dumps.
• Point authors at these pages, not a local guide\ folder.