Metadata-Version: 2.4
Name: dcc-mcp-speedtree
Version: 0.1.1
Summary: Local-first DCC-MCP adapter for SpeedTree official capabilities
Author-email: loonghao <hal.long@outlook.com>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: dcc-mcp-core<1.0.0,>=0.20.22
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: ruff>=0.11; extra == "test"
Requires-Dist: build>=1; extra == "test"

# dcc-mcp-speedtree

Create and edit native SpeedTree generator graphs, regenerate them with the
licensed Modeler command-line exporter, and hand verified assets to another
DCC-MCP adapter. Graph authoring uses the observed SPM/STT file format and is
experimental; full live Modeler control is not yet available.

## Native node showcase

![Willow and grass created through successive generator operations](docs/images/native-node-workflow.gif)

The willow grows from trunk to primary branches, drooping branches, and leaf
cards. The grass adds stalk and frond generators, then edits the width curve
to taper the blades. Each step is a new SPM, regenerated by **SpeedTree Modeler
10.1.0**. The diagram comes from the saved generator IDs and links.

| Native output | Generators | Vertices | Faces |
| --- | ---: | ---: | ---: |
| Willow | 5 | 7,092 | 6,166 |
| Grass | 3 | 27,540 | 59,400 |

These are procedural geometry studies. The images use unchanged exported OBJ
geometry with display materials in headless Blender; they are not Modeler
screenshots or native material acceptance. No UI automation builds either
asset. [Reproduce the workflow](docs/node-authoring.md) ·
[Operation and geometry evidence](docs/node-showcase-provenance.json) ·
[Native capability matrix](docs/native-capability-matrix.md).

## Start

This is a source preview. Install the checkout with `python -m pip install -e .`,
then configure the installed Modeler executable:

```powershell
$env:DCC_MCP_SPEEDTREE_EXECUTABLE = "C:/Applications/SpeedTree/SpeedTree_Modeler.exe"
dcc-mcp-speedtree
```

The standalone service has its own lifetime and OS-assigned port. Discover it
with `dcc-mcp-cli --gateway local list`, then search and describe its tools.
Optional GUI binding uses `--pid <PID> --window-handle <HWND>` and validates
that the window belongs to the named executable. GUI actions must use the
project-owned `dcc-cua` / `ui-control` route with a fresh exact binding.

## Agent workflow

Read the [capability audit](docs/capability-audit.md) for the complete tool chain
and the limits of modeling, materials, LOD, wind, collision, and cancellation.
Use `inspect_capabilities` for a machine-readable scope report without a GUI.

1. `discover_templates` and `inspect_authoring_catalog` enumerate installed
   generator templates and their stored properties. `inspect_graph` and
   `inspect_properties` read the selected source. `edit_graph` adds, duplicates,
   removes, connects, disconnects, renames, hides, or changes properties and
   existing curve components, writing a **new** SPM/STT.
2. `discover_content` locates installed SPM samples and Games/VFX presets;
   `inspect_preset` reports the selected settings.
3. `plan_export` checks an SPM, preset, format, and **new** output directory.
4. `export_batch` exports 1–16 SPMs through `-export_game` or `-export`, with
   `-export_options`. Supported extensions are `st9`, `st`, `fbx`, `obj`,
   `abc`, and `usd`; availability still depends on product version/license.
5. `export_status` reads progress while Core runs the job; Core cancellation
   stops the owned export process (`DELETE /v1/jobs/{id}` on the owning service). `verify_export` checks the recorded file hashes before handoff. Each tree
   lives in its own directory with its textures and material sidecar.
6. `plan_import` prepares a verified handoff. Discover the destination adapter's importer, import into a new destination,
   and read back geometry, materials, dependencies, transforms, and animation.

The [asset bundle contract](docs/asset-bundle.md) separates export evidence from
target import evidence. [Format and target coverage](docs/compatibility.md)
records the tested combinations and feature limits. The service never runs a
caller-supplied executable or shell command. Existing output directories are
rejected; timeout, failed exit, changed input, missing mesh, or missing explicit
material dependency stops the batch and preserves a partial manifest.

## Unreal

![Real SpeedTree source and Unreal Engine result](docs/images/speedtree-to-unreal.png)

The same Palm asset in Modeler 10.1 and UE 5.5, using native SpeedTree
materials after explicit unit, UV, and texture repairs on a duplicate.
The final mesh height is 12.34384 m; collision scale and dynamic wind remain unverified.
[Capture provenance and repair notes](docs/showcase.md).

Use the installed Unreal ST9 Games preset for a modern Unreal workflow.
`.spm` is the authoring source, not a Content Browser import format.
`inspect_unreal_project` reports descriptor entries only: a missing entry is
`null` because engine plugin defaults may enable it. Check installation and
loaded modules through `dcc-mcp-unreal`; configure missing plugins only after
the user authorizes the concrete plan. Configuration and restarts belong to
the target adapter. This service does not silently install or enable plugins.

After importing each ST9 via `unreal-assets.import_asset`, read back the mesh
and dependencies. Successful export or enabled plugins alone do not prove a
usable imported asset, correct wind, collision, or rendered appearance.

## Official references

- [Command-line export](https://docs.unity3d.com/speedtree-modeler/manual/export-from-the-command-line.html)
- [Games export options](https://docs.unity3d.com/speedtree-modeler/manual/games-export-options.html)
- [VFX formats and options](https://docs.unity3d.com/speedtree-modeler/manual/vfx-export-options.html)
- [Unreal integration](https://docs.unity3d.com/speedtree-modeler/manual/import-to-unreal.html)

The repository contains no vendor binaries, licensed sample assets, SDK files,
or licensing material. Generated vendor sidecars can contain source-machine
paths; keep raw exports and diagnostics local unless reviewed for sharing.
