jahro-commands

Files (1)

• SKILL.md

SKILL.md (first lines)

# Jahro Commands

Help users add runtime-callable debug commands to Unity code using Jahro's `[JahroCommand]` attribute system.

## Workflow

1. **Analyze** the user's code — identify methods that are good command candidates
2. **Generate** correct `[JahroCommand]` attributes with proper syntax
3. **Add registration** if needed (instance methods require `RegisterObject`)
4. **VERIFY** — "Enter Play Mode, press ~, check the Commands tab"

## Analyzing Code for Command Candidates

When the user shares a class, identify methods worth exposing as commands:

**Good candidates:**
- Public methods that change game state (damage, heal, spawn, teleport, reset)
- Methods used for testing and tuning (set difficulty, add currency, skip level)
- Diagnostic methods (print stats, dump state, force GC)
- Methods with simple parameter types (int, float, bool, string, Vector2, Vector3, enum)

**Skip these:**
- Unity lifecycle methods (Update, Start, Awake, OnEnable, OnDisable, OnDestroy)
- Private implementation details the developer wouldn't want to call manually
- Methods with complex parameter types (custom classes, interfaces, delegates)
- Property getters/setters (use `[JahroWatch]` for monitoring instead)

## Attribute Syntax

```csharp
[JahroCommand("command-name", "GroupName", "Short description of what it does")]
```

Constructor: `[JahroCommand(string name, string group, string description)]`

All parameters are optional. Defaults: name = method name, group = "Default", description = "".

### Naming conventions

- **Command name**: kebab-case (`"spawn-enemy"`, `"add-gold"`, `"set-difficulty"`)
- **Group name**: PascalCase or Title Case (`"Cheats"`, `"Spawning"`, `"Game"`)
- **Description**: Imperative, concise (`"Spawn enemy at position"`, `"Add gold to player"`)

### Complete example

```csharp
using JahroConsole;
using UnityEngine;

public class PlayerController : MonoBehaviour
{
    public float health = 100f;

    [JahroCommand("heal", "Player", "Restore health by amount")]
    public void Heal(float amount) { health = Mathf.Min(health + amount, 100f); }

    [JahroCommand("teleport", "Player", "Teleport to position")]
    public void Teleport(Vector3 position) { transform.position = position; }

    [JahroCommand("reset-pos", "Player", "Reset to origin")]
    public void ResetPosition() { transform.position = Vector3.zero; }

    void OnEnable()  => Jahro.RegisterObject(this);
    void OnDisable() => Jahro.UnregisterObject(this);
}
```

## Registration Pattern

### Instance methods — require RegisterObject

Any non-static method with `[JahroCommand]` needs the owning object registered so Jahro can invoke it:

```csharp
void OnEnable()  => Jahro.RegisterObject(this);
void OnDisable() => Jahro.UnregisterObject(this);
```

This same call also registers `[JahroWatch]` attributes on the class. If the class already has RegisterObject (e.g., for watchers), do not add a second call.

Read `references/common-patterns.md` for the full lifecycle pattern and anti-patterns.

### Static methods — no registration needed

Static methods are discovered via assembly scanning:

```csharp
public class DebugCommands
{
    [JahroCommand("restart-level", "Game", "Restart current level")]
    public static void RestartLevel()
    {
        UnityEngine.SceneManagement.SceneManager.LoadScene(0);
    }
}
```

### Decision guide

| Method type | Needs RegisterObject? | Why |
|:------------|:---------------------|:----|
| `public void Foo()` (instance) | Yes | Jahro needs the object reference to call it |
| `public static void Foo()` | No | Called on the class, discovered via assembly scan |
| `public void Foo()` on a class that already has RegisterObject | No extra work | Already registered |

## Supported Parameter Types

Commands accept these parameter types:

| Type | Text Mode input | Visual Mode input |
|:-----|:---------------|:-----------------|
| `int` | `42` | Number field |
| `float` | `3.14` | Decimal field |
| `bool` | `true` / `false` | Toggle switch |
| `string` | `hello world` | Text field |
| `Vector2` | `1.5 2.0` | X/Y fields |
| `Vector3` | `10 2.5 -7` | X/Y/Z fields |
| `enum` (any) | `Hard` (name) | Dropdown selector |

From jahro-console/unity-agent-skills, MIT.

More from jahro-console/unity-agent-skills