jahro-console/jahro-commands

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

[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

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:

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:

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 |

Maximum 3 parameters per command. For full type details, read references/api-reference.md.

Command Overloads

Same command name with different parameter signatures:

[JahroCommand("spawn-enemy", "Spawning", "Spawn one enemy at position")]
public void SpawnEnemy(Vector3 position) { /* ... */ }

[JahroCommand("spawn-enemy", "Spawning", "Spawn N enemies")]
public void SpawnEnemy(int count) { /* ... */ }

Text Mode resolves the correct overload by parameter count and type conversion.

Return Values

Commands that return string display the result in the console log:

[JahroCommand("get-pos", "Debug", "Print player position")]
public static string GetPlayerPosition()
{
    return $"Position: {Player.Instance.transform.position}";
}

Dynamic Command Registration

For commands created at runtime instead of compile time. Use when wrapping external APIs, creating commands from data, or in non-MonoBehaviour systems.

// No parameters
Jahro.RegisterCommand("clear-cache", "Maintenance", "Clear local cache",
    () => PlayerPrefs.DeleteAll());

// One typed parameter
Jahro.RegisterCommand<int>("add-gold", "Cheats", "Add gold",
    amount => Player.Gold += amount);

// Two parameters
Jahro.RegisterCommand<int, float>("set-stats", "Tuning", "Set health and speed",
    (health, speed) => { Player.Health = health; Player.Speed = speed; });

Parameter order for dynamic registration: (name, description, groupName, callback). This differs from the attribute order (name, group, description).

Register command on existing object method:

var mgr = FindObjectOfType<GameManager>();
Jahro.RegisterCommand("restart", "Game", "Restart level",
    mgr, nameof(GameManager.RestartLevel));

Cleanup:

Jahro.UnregisterCommand("clear-cache");
Jahro.UnregisterCommand("restart", "Game");

Read references/api-reference.md for all RegisterCommand overloads (0-3 generic parameters).

Command Organization

Group naming strategy

Organize commands by functional area:

"Player"    — heal, teleport, reset, set-speed
"Spawning"  — spawn-enemy, spawn-wave, clear-enemies
"Cheats"    — god-mode, add-gold, unlock-all
"Game"      — restart-level, set-difficulty, skip-level
"Debug"     — dump-state, gc-collect, toggle-fps

Visual Mode vs Text Mode

Commands work in both modes automatically. Consider the target audience:

• Text Mode — fast for developers who know command names. Autocomplete helps. Vector3 entered as 10 2.5 -7.
• Visual Mode — browsable groups with descriptions, form-based parameter input. Touch-friendly on mobile. Enum parameters render as dropdown selectors.

When designing commands for QA (non-developers), prefer:

• Simple parameter types (bool, enum, int) over Vector3
• Descriptive names and descriptions
• Logical groups that match QA workflows

Favorites and Recent

Users can star frequently-used commands for quick access. The last 10 executed commands always appear in the Recent section. Command names and groups help discoverability — be descriptive.

Contextual Awareness

When you see these patterns in user code, proactively suggest:

| Pattern in code | Suggestion | |:---------------|:-----------| | [JahroCommand] already present | Offer improvements (better groups, descriptions, missing commands) | | OnGUI() with GUI.Button debug commands | Migrate to [JahroCommand] — Visual Mode replaces the button UI | | Public methods that modify game state | Suggest exposing as commands | | Custom command parser (string → command) | Migrate to Jahro's typed command system |

Verification

After generating commands, always include:

Verify: Enter Play Mode → press ~ → switch to the Commands tab (or Visual Mode). Confirm your commands appear in the correct groups. Try executing one to confirm it works.

If commands don't appear, suggest the jahro-troubleshooting skill — common causes: missing RegisterObject, wrong assembly selected, JAHRO_DISABLE active.