soft-ue-cli 1.0.0__tar.gz

soft_ue_cli-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+*.so
+*.dylib

soft_ue_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soft-ue-expert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soft_ue_cli-1.0.0/PKG-INFO

@@ -0,0 +1,427 @@
+Metadata-Version: 2.4
+Name: soft-ue-cli
+Version: 1.0.0
+Summary: CLI tool for controlling Unreal Engine via soft-ue-bridge plugin
+Project-URL: Homepage, https://github.com/softdaddy-o/soft-ue-cli
+Project-URL: Repository, https://github.com/softdaddy-o/soft-ue-cli
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# soft-ue-cli
+
+[![PyPI version](https://img.shields.io/pypi/v/soft-ue-cli.svg)](https://pypi.org/project/soft-ue-cli/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/soft-ue-cli.svg)](https://pypi.org/project/soft-ue-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Control Unreal Engine 5 from the command line.** soft-ue-cli is a Python CLI that lets [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's AI coding agent) -- or any terminal workflow -- spawn actors, edit Blueprints, inspect materials, run Play-In-Editor sessions, capture screenshots, profile performance, and execute 50+ other operations inside a running UE5 editor or packaged build.
+
+One pip install. One plugin copy. Zero manual editor clicks.
+
+```
+Claude Code  -->  soft-ue-cli (Python)  -->  HTTP/JSON-RPC  -->  SoftUEBridge plugin (inside UE)
+```
+
+---
+
+## Why soft-ue-cli?
+
+- **AI-native UE automation** -- purpose-built so Claude Code can read, modify, and test Unreal Engine projects without a human touching the editor.
+- **50+ commands** covering actors, Blueprints, materials, StateTrees, widgets, assets, PIE sessions, profiling, and more.
+- **Works everywhere UE runs** -- editor, cooked builds, Windows, macOS, Linux.
+- **Single dependency** -- only requires `httpx`. No heavy SDK, no editor scripting setup.
+- **Team-friendly** -- conditional compilation via `SOFT_UE_BRIDGE` environment variable means only developers who need the bridge get it compiled in.
+
+---
+
+## Quick Start
+
+### 1. Install the CLI
+
+```bash
+pip install soft-ue-cli
+```
+
+### 2. Install the plugin into your UE project
+
+```bash
+soft-ue-cli setup /path/to/YourProject
+```
+
+This copies the bundled **SoftUEBridge** C++ plugin into your project's `Plugins/` directory.
+
+### 3. Enable the plugin
+
+Add the following entry to the `"Plugins"` array in your `.uproject` file:
+
+```json
+{"Name": "SoftUEBridge", "Enabled": true}
+```
+
+### 4. Rebuild and launch Unreal Engine
+
+After regenerating project files and rebuilding, launch the editor. Look for this log line to confirm the bridge is running:
+
+```
+LogSoftUEBridge: Bridge server started on port 8080
+```
+
+### 5. Verify the connection
+
+```bash
+soft-ue-cli check-setup
+```
+
+You should see all checks pass:
+
+```
+[OK]   Plugin files found.
+[OK]   SoftUEBridge enabled in YourGame.uproject.
+[OK]   Bridge server reachable.
+```
+
+### 6. Tell Claude Code about the CLI
+
+Create or append to your project's `CLAUDE.md`:
+
+```markdown
+## Unreal Engine control
+
+`soft-ue-cli` controls this UE project via the SoftUEBridge plugin.
+Run `soft-ue-cli --help` to see all available commands.
+The game or editor must be running with SoftUEBridge enabled before using UE commands.
+```
+
+Now Claude Code can autonomously control your Unreal Engine project.
+
+---
+
+## How It Works
+
+```
+Claude Code
+    |
+    |  (runs CLI commands in terminal)
+    v
+soft-ue-cli  (Python process)
+    |
+    |  HTTP / JSON-RPC requests
+    v
+SoftUEBridge plugin  (C++ UGameInstanceSubsystem, inside UE process)
+    |
+    |  Native UE API calls on the game thread
+    v
+Unreal Engine 5 editor or runtime
+```
+
+The **SoftUEBridge** plugin is a lightweight C++ `UGameInstanceSubsystem` that starts an embedded HTTP server on port 8080 when UE launches. The CLI sends JSON-RPC requests to this server, and the plugin executes the corresponding UE operations on the game thread, returning structured JSON responses.
+
+All commands output JSON to stdout (except `get-logs --raw`). Exit code 0 means success, 1 means error.
+
+---
+
+## Complete Command Reference
+
+Every command is available via `soft-ue-cli <command>`. Run `soft-ue-cli <command> --help` for detailed options.
+
+### Setup and Diagnostics
+
+| Command | Description |
+|---------|-------------|
+| `setup` | Copy SoftUEBridge plugin into a UE project |
+| `check-setup` | Verify plugin files, .uproject settings, and bridge server reachability |
+| `status` | Health check -- returns server status |
+| `project-info` | Get project name, engine version, target platforms, and module info |
+
+### Actor and Level Operations
+
+| Command | Description |
+|---------|-------------|
+| `spawn-actor` | Spawn an actor by class at a given location and rotation |
+| `query-level` | List actors in the current level with transforms, filtering by class or name |
+| `call-function` | Call any `BlueprintCallable` `UFUNCTION` on an actor |
+| `set-property` | Set a `UPROPERTY` value on an actor by name |
+| `add-component` | Add a component to an existing actor |
+
+### Blueprint Inspection and Editing
+
+| Command | Description |
+|---------|-------------|
+| `query-blueprint` | Inspect a Blueprint asset -- components, variables, functions, event dispatchers |
+| `query-blueprint-graph` | Inspect event graphs, function graphs, and node connections |
+| `add-graph-node` | Add a node to a Blueprint or Material graph |
+| `remove-graph-node` | Remove a node from a graph |
+| `connect-graph-pins` | Connect two pins between graph nodes |
+| `disconnect-graph-pin` | Disconnect a specific pin |
+| `set-node-position` | Batch-set node positions for graph layout |
+
+### Asset Management
+
+| Command | Description |
+|---------|-------------|
+| `query-asset` | Search the Content Browser by name, class, or path -- also inspect DataTables |
+| `create-asset` | Create new Blueprint, Material, DataTable, or other asset types |
+| `delete-asset` | Delete an asset |
+| `set-asset-property` | Set a property on a Blueprint CDO or component |
+| `get-asset-diff` | Get property-level diff of an asset vs. source control |
+| `get-asset-preview` | Get a thumbnail/preview image of an asset |
+| `open-asset` | Open an asset in the editor |
+| `find-references` | Find assets, variables, or functions referencing a given asset |
+
+### Material Inspection
+
+| Command | Description |
+|---------|-------------|
+| `query-material` | Inspect Material or Material Instance -- parameters, nodes, connections |
+
+### Class and Type Inspection
+
+| Command | Description |
+|---------|-------------|
+| `class-hierarchy` | Inspect class inheritance chains -- ancestors, descendants, or both |
+
+### Play-In-Editor (PIE) Control
+
+| Command | Description |
+|---------|-------------|
+| `pie-session` | Start, stop, pause, resume PIE -- also query actor state during play |
+| `pie-input` | Send keyboard, mouse, gamepad, or AI-move input to a PIE session |
+
+### Screenshot and Visual Capture
+
+| Command | Description |
+|---------|-------------|
+| `capture-screenshot` | Capture the editor viewport, PIE window, or a specific editor panel |
+
+### Logging and Console Variables
+
+| Command | Description |
+|---------|-------------|
+| `get-logs` | Read the UE output log with optional category and text filters |
+| `get-console-var` | Read the value of a console variable (CVar) |
+| `set-console-var` | Set a console variable value |
+
+### Python Scripting in UE
+
+| Command | Description |
+|---------|-------------|
+| `run-python-script` | Execute a Python script inside UE's embedded Python interpreter |
+| `save-script` | Save a reusable Python script to the local script library |
+| `list-scripts` | List all saved Python scripts |
+| `delete-script` | Delete a saved script |
+
+### StateTree Editing
+
+| Command | Description |
+|---------|-------------|
+| `query-statetree` | Inspect a StateTree asset -- states, tasks, transitions |
+| `add-statetree-state` | Add a state to a StateTree |
+| `add-statetree-task` | Add a task to a StateTree state |
+| `add-statetree-transition` | Add a transition between StateTree states |
+| `remove-statetree-state` | Remove a state from a StateTree |
+
+### Widget Blueprint Inspection
+
+| Command | Description |
+|---------|-------------|
+| `inspect-widget-blueprint` | Inspect UMG Widget Blueprint hierarchy, bindings, and properties |
+| `add-widget` | Add a widget to a Widget Blueprint |
+
+### DataTable Editing
+
+| Command | Description |
+|---------|-------------|
+| `add-datatable-row` | Add or update a row in a DataTable asset |
+
+### Performance Profiling (UE Insights)
+
+| Command | Description |
+|---------|-------------|
+| `insights-capture` | Start or stop a UE Insights trace capture |
+| `insights-list-traces` | List available trace files |
+| `insights-analyze` | Analyze a trace file for CPU, GPU, or memory hotspots |
+
+### Build and Live Coding
+
+| Command | Description |
+|---------|-------------|
+| `build-and-relaunch` | Trigger a full C++ rebuild and optionally relaunch the editor |
+| `trigger-live-coding` | Trigger a Live Coding compile (hot reload) |
+
+---
+
+## Usage Examples
+
+### Spawn an actor at a specific location
+
+```bash
+soft-ue-cli spawn-actor BP_Enemy --location 100,200,50 --rotation 0,90,0
+```
+
+### Query all actors of a specific class
+
+```bash
+soft-ue-cli query-level --class-filter StaticMeshActor --limit 50
+```
+
+### Call a BlueprintCallable function
+
+```bash
+soft-ue-cli call-function BP_GameMode SetDifficulty --args '{"Level": 3}'
+```
+
+### Inspect a Blueprint's components and variables
+
+```bash
+soft-ue-cli query-blueprint /Game/Blueprints/BP_Player --include components,variables
+```
+
+### Start a PIE session and send input
+
+```bash
+soft-ue-cli pie-session start --mode SelectedViewport
+soft-ue-cli pie-input press --key SpaceBar
+soft-ue-cli pie-session stop
+```
+
+### Capture a screenshot of the editor viewport
+
+```bash
+soft-ue-cli capture-screenshot viewport --output screenshot.png
+```
+
+### Edit a Blueprint graph programmatically
+
+```bash
+soft-ue-cli add-graph-node /Game/BP_Player K2Node_CallFunction \
+  --properties '{"FunctionReference": {"MemberName": "PrintString"}}'
+soft-ue-cli connect-graph-pins /Game/BP_Player node1 "exec" node2 "execute"
+```
+
+### Profile with UE Insights
+
+```bash
+soft-ue-cli insights-capture start --channels CPU,GPU
+# ... run your scenario ...
+soft-ue-cli insights-capture stop
+soft-ue-cli insights-analyze latest --analysis-type cpu
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SOFT_UE_BRIDGE_URL` | *(none)* | Full bridge URL override (e.g. `http://192.168.1.10:8080`) |
+| `SOFT_UE_BRIDGE_PORT` | `8080` | Port override when using localhost |
+| `SOFT_UE_BRIDGE` | *(none)* | Set to `1` to enable conditional compilation in `Target.cs` |
+
+### Server Discovery Order
+
+The CLI finds the bridge server using this priority:
+
+1. `--server` command-line flag
+2. `SOFT_UE_BRIDGE_URL` environment variable
+3. `SOFT_UE_BRIDGE_PORT` environment variable (constructs `http://127.0.0.1:<port>`)
+4. `.soft-ue-bridge/instance.json` file (searched upward from the current working directory -- written automatically by the plugin at startup)
+5. `http://127.0.0.1:8080` (default fallback)
+
+### Conditional Compilation for Teams
+
+If you want only specific developers to compile the bridge plugin (to avoid any overhead for artists or designers), use the `SOFT_UE_BRIDGE` environment variable in your `Target.cs`:
+
+```csharp
+// MyGameEditor.Target.cs
+if (Environment.GetEnvironmentVariable("SOFT_UE_BRIDGE") == "1")
+{
+    ExtraModuleNames.Add("SoftUEBridge");
+}
+```
+
+Developers who need the bridge set `SOFT_UE_BRIDGE=1` in their environment. Everyone else builds without it.
+
+---
+
+## Compatibility
+
+| Requirement | Supported Versions |
+|-------------|--------------------|
+| **Unreal Engine** | 5.3, 5.4, 5.5 |
+| **Python** | 3.10+ |
+| **Platforms** | Windows, macOS, Linux |
+| **Build types** | Editor, Development, Shipping (cooked/packaged) |
+| **Dependencies** | `httpx >= 0.27` (sole runtime dependency) |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/softdaddy-o/soft-ue-cli
+cd soft-ue-cli
+pip install -e .
+pytest -v
+```
+
+---
+
+## Frequently Asked Questions
+
+### What is soft-ue-cli?
+
+soft-ue-cli is a Python command-line tool that controls Unreal Engine 5 from the terminal. It communicates with a C++ plugin (SoftUEBridge) running inside UE via HTTP/JSON-RPC, enabling automation of actor spawning, Blueprint editing, material inspection, Play-In-Editor sessions, screenshot capture, performance profiling, and 50+ other operations.
+
+### How does Claude Code use soft-ue-cli to control Unreal Engine?
+
+Claude Code runs soft-ue-cli commands in the terminal just like a developer would. By adding a `CLAUDE.md` file to your UE project that describes the available commands, Claude Code can autonomously query your level, spawn actors, edit Blueprints, run PIE sessions, and iterate on your game -- all without manual editor interaction.
+
+### Can I use soft-ue-cli without Claude Code?
+
+Yes. soft-ue-cli is a standard Python CLI. You can use it in shell scripts, CI/CD pipelines, custom automation tools, or any workflow that can invoke command-line programs. Every command outputs structured JSON, making it easy to parse and integrate.
+
+### Does it work with packaged/cooked Unreal Engine builds?
+
+Yes. The SoftUEBridge plugin works in both the UE editor and in cooked/packaged builds (Development and Shipping configurations). This makes it useful for automated testing of packaged games.
+
+### What Unreal Engine versions are supported?
+
+soft-ue-cli supports Unreal Engine 5.3, 5.4, and 5.5. The C++ plugin uses stable engine APIs and is compatible across these versions without modification.
+
+### Is there any runtime performance impact?
+
+The SoftUEBridge plugin adds a lightweight HTTP server that listens on a single port. When no requests are being made, the overhead is negligible. The server processes requests on the game thread to ensure thread safety with UE APIs. For production builds where you do not want the bridge, use conditional compilation via the `SOFT_UE_BRIDGE` environment variable.
+
+### How do I change the default port?
+
+Set the `SOFT_UE_BRIDGE_PORT` environment variable before launching UE, or use the `--server` flag when running CLI commands. The default port is 8080.
+
+### Can multiple UE instances run simultaneously?
+
+Yes. Each UE instance writes its port to a `.soft-ue-bridge/instance.json` file in the project directory. Use `SOFT_UE_BRIDGE_URL` or `--server` to target a specific instance when multiple are running.
+
+### How do I edit Blueprints from the command line?
+
+Use `query-blueprint-graph` to inspect existing graph nodes, `add-graph-node` to create new nodes, `connect-graph-pins` to wire them together, and `remove-graph-node` to delete nodes. This enables fully programmatic Blueprint construction -- useful for AI-driven development and automated testing.
+
+### What is the difference between soft-ue-cli and Unreal Engine Remote Control?
+
+Unreal Engine's built-in Remote Control API focuses on property access and preset-based workflows. soft-ue-cli provides a broader command set specifically designed for AI coding agents -- including Blueprint graph editing, StateTree manipulation, PIE session control, UE Insights profiling, widget inspection, and asset creation -- with a simpler setup process (one pip install, one plugin copy).
+
+---
+
+## License
+
+MIT License. See [LICENSE](https://github.com/softdaddy-o/soft-ue-cli/blob/main/LICENSE) for details.
+
+---
+
+## Links
+
+- **PyPI**: [pypi.org/project/soft-ue-cli](https://pypi.org/project/soft-ue-cli/)
+- **GitHub**: [github.com/softdaddy-o/soft-ue-cli](https://github.com/softdaddy-o/soft-ue-cli)
+- **Claude Code**: [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code)