jahro-commands

--- name: jahro-commands description: > Analyzes C# classes and generates [JahroCommand] attributes with correct syntax, RegisterObject patterns, and group organization. Use when the user wants to add runtime commands, cheats, or debug actions to Unity classes, or mentions JahroCommand, console commands, runtime cheats, or debug actions. --- # 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 | Maximum 3 parameters per command. For full type details, read `references/api-reference.md`. ## Command Overloads Same command name with different parameter signatures: ```csharp [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: ```csharp [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. ```csharp // 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: ```csharp var mgr = FindObjectOfType<GameManager>(); Jahro.RegisterCommand("restart", "Game", "Restart level", mgr, nameof(GameManager.RestartLevel)); ``` Cleanup: ```csharp 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.

1. **Identify your goal**: Replace [SPECIFIC_TASK] with your exact need (e.g., 'audit security vulnerabilities' or 'optimize build performance'). 2. **Specify the tool/platform**: Replace [TOOL/PLATFORM] with the target (e.g., 'jahro CLI', 'jahro for Docker', or 'jahro in GitHub Actions'). 3. **Set the quantity**: Replace [NUMBER] with how many commands you want (e.g., 3 for quick fixes or 10 for complex workflows). 4. **Run and refine**: Copy the generated commands into your terminal or CI/CD pipeline. Use `--help` in jahro CLI to explore additional flags. 5. **Log outputs**: Redirect command outputs to files (e.g., `jahro audit --output report.txt`) for review or integration with other tools. Tip: For complex tasks, combine commands using pipes (e.g., `jahro scan | jahro filter --critical`) or chain them in scripts.