[arhidavid]

Problem and behavior

Follow-up to thekannen/battlemap-mcp#17: import_image already shipped in upstream 1.4.2. This PR is the pack-builder half only, based on current upstream main / 1.4.2.

create_image_pack(filename, name, images, pack_id="", author="") builds a native .dungeondraft_pack of named, tagged PNG objects. The archive includes the root registration manifest and inner pack.json, plus native tags/sets. Existing files are never overwritten. Writes are limited to Dungeondraft’s configured asset folder.

Workflow after create: restart Dungeondraft (verified live) — or rescan packs in the Assets window (unverified without restart) → prepare_map_with_packs with the returned id → list_assets / search_pack_contents / place_object. search_pack_contents can already see the new archive on disk before a rescan/restart.

Design choice (tool count)

Adds one companion tool: create_image_pack.

• Not merged into import_image (embed-in-map vs library pack are different jobs).
• Not merged into prepare_map_with_packs (that tool rewrites map headers; packing PNGs does not belong there).
• Does not add refresh_asset_packs (see note 3 below).

Addressing thekannen’s #17 notes

1. No-clobber / portable publish. Replaced os.link with O_CREAT | O_EXCL open of the final destination, then write + fsync. That works on exFAT, FAT32, and network shares where hard links fail. A competing writer that claims the name first surfaces as “already exists”; this call only unlinks a file it created.

2. Where packs may be written. filename is a bare name (same style as prepare_map_with_packs). The destination is resolved under pack_contents.assets_directory() only (config.ini custom_assets_directory or BATTLEMAP_MCP_ASSETS_DIR). Absolute/outside paths are refused.

3. refresh_asset_packs / Assets.UpdateTree — deferred. The Add native PNG object import and optional tagged asset packs #17 live notes reported a native read error and editor exit when an invalid early test archive was moved during cleanup while Dungeondraft was running; that “do not move mounted packs” restriction remains documented. Neither our cloud environment nor our live pass isolated UpdateTree, and this PR does not expose refresh. Safe path: ask the user to restart Dungeondraft (or rescan in the Assets window), then call prepare_map_with_packs. If a later live session clearly shows refresh-only is safe, that can be a small follow-up.

4. Fewer new tools. One new tool instead of three (import_image already upstream; refresh omitted).

Implementation

• Extends server/battlemap_mcp/image_import.py with pack building (reuses PNG validation).
• Registers create_image_pack as a companion tool in bridge_client.py.
• Docs: docs/image-pack.md; PROTOCOL / docs README updated.
• No bridge / GDScript changes; no re-add of import_image.

Validation

Offline CI/checks:

• Full python server/tools/gate.py passed (format, lint, bridge/contract/lifecycle/engine, skills, agent docs, types, tests).
• tools/release.py check passed.
• New/extended offline coverage in server/tests/test_image_import.py: pack round-trip, root manifest, no-clobber race, asset-folder path limit, reserved Colorable tag, corrupt PNG refusal.

Live Windows + Dungeondraft check on a61209d (running the PR’s 1.4.2-matched bridge source hash):

• python server/tools/gate.py passed on Windows with a fresh temporary folder.
• create_image_pack refused an outside path (../…), wrote a two-PNG .dungeondraft_pack inside Dungeondraft’s configured asset folder, and refused to overwrite it (file hash stayed identical); search_pack_contents found both tags on disk immediately.
• After restarting Dungeondraft, list_asset_packs saw the pack, prepare_map_with_packs added it to a scratch map copy, both tagged objects were discoverable and placeable, and both survived save and reopen; pixel checks confirmed transparent centers in the DD2VTT export.
• Note: the manual Assets-window rescan path without restarting Dungeondraft was not tested live.
• Dungeondraft exited cleanly before removing the temporary pack (do not move/remove mounted packs while the editor runs).

Documentation pages needing maintainer update

• Public tool reference and asset-pack workflow at https://knownframe.com/battlemap-mcp/docs/

AI assistance

Code and PR text were written with AI assistance (Cursor / Codex).

[thekannen]

Thank you, David. This handles every point from #17: exclusive create, writes limited to the asset folder, no refresh tool, and one new tool instead of three. The Windows live run (restart, include, place, save and reopen, transparency in the DD2VTT export) is exactly the evidence it needed.

I've ported it as your commit for 1.4.3, with a few changes:

• Restart is the documented step. The tool description, result note and doc offered rescanning the Assets window as an equal option, but only a restart was tested, so rescanning is now marked untested.
• A pack id an installed pack already uses is refused. Two files with one id leave Dungeondraft mounting only one of them. A generated id skips ids in use.
• Small checks: author is capped at 120 characters, control characters are refused in names and tags, and tags are de-duplicated once.
• Tests: the corrupt-PNG test for read_png is restored as it was, and the pack case is a separate test.

It'll ship in 1.4.3, credited to you. I'll update the asset-pack docs page on knownframe.com. Thanks again for following up on this.