appiq-solution 1.2.0 → 1.3.1

package/#Tools/APPIQ-METHOD/expansion-packs/bmad-2d-unity-game-dev/data/development-guidelines.md

@@ -0,0 +1,590 @@
+# Game Development Guidelines (Unity & C#)
+
+## Overview
+
+This document establishes coding standards, architectural patterns, and development practices for 2D game development using Unity and C#. These guidelines ensure consistency, performance, and maintainability across all game development stories.
+
+## C# Standards
+
+### Naming Conventions
+
+**Classes, Structs, Enums, and Interfaces:**
+
+- PascalCase for types: `PlayerController`, `GameData`, `IInteractable`
+- Prefix interfaces with 'I': `IDamageable`, `IControllable`
+- Descriptive names that indicate purpose: `GameStateManager` not `GSM`
+
+**Methods and Properties:**
+
+- PascalCase for methods and properties: `CalculateScore()`, `CurrentHealth`
+- Descriptive verb phrases for methods: `ActivateShield()` not `shield()`
+
+**Fields and Variables:**
+
+- `private` or `protected` fields: camelCase with an underscore prefix: `_playerHealth`, `_movementSpeed`
+- `public` fields (use sparingly, prefer properties): PascalCase: `PlayerName`
+- `static` fields: PascalCase: `Instance`, `GameVersion`
+- `const` fields: PascalCase: `MaxHitPoints`
+- `local` variables: camelCase: `damageAmount`, `isJumping`
+- Boolean variables with is/has/can prefix: `_isAlive`, `_hasKey`, `_canJump`
+
+**Files and Directories:**
+
+- PascalCase for C# script files, matching the primary class name: `PlayerController.cs`
+- PascalCase for Scene files: `MainMenu.unity`, `Level01.unity`
+
+### Style and Formatting
+
+- **Braces**: Use Allman style (braces on a new line).
+- **Spacing**: Use 4 spaces for indentation (no tabs).
+- **`using` directives**: Place all `using` directives at the top of the file, outside the namespace.
+- **`this` keyword**: Only use `this` when necessary to distinguish between a field and a local variable/parameter.
+
+## Unity Architecture Patterns
+
+### Scene Lifecycle Management
+
+**Loading and Transitioning Between Scenes:**
+
+```csharp
+// SceneLoader.cs - A singleton for managing scene transitions.
+using UnityEngine;
+using UnityEngine.SceneManagement;
+using System.Collections;
+
+public class SceneLoader : MonoBehaviour
+{
+    public static SceneLoader Instance { get; private set; }
+
+    private void Awake()
+    {
+        if (Instance != null && Instance != this)
+        {
+            Destroy(gameObject);
+            return;
+        }
+        Instance = this;
+        DontDestroyOnLoad(gameObject);
+    }
+
+    public void LoadGameScene()
+    {
+        // Example of loading the main game scene, perhaps with a loading screen first.
+        StartCoroutine(LoadSceneAsync("Level01"));
+    }
+
+    private IEnumerator LoadSceneAsync(string sceneName)
+    {
+        // Load a loading screen first (optional)
+        SceneManager.LoadScene("LoadingScreen");
+
+        // Wait a frame for the loading screen to appear
+        yield return null;
+
+        // Begin loading the target scene in the background
+        AsyncOperation asyncLoad = SceneManager.LoadSceneAsync(sceneName);
+
+        // Don't activate the scene until it's fully loaded
+        asyncLoad.allowSceneActivation = false;
+
+        // Wait until the asynchronous scene fully loads
+        while (!asyncLoad.isDone)
+        {
+            // Here you could update a progress bar with asyncLoad.progress
+            if (asyncLoad.progress >= 0.9f)
+            {
+                // Scene is loaded, allow activation
+                asyncLoad.allowSceneActivation = true;
+            }
+            yield return null;
+        }
+    }
+}
+```
+
+### MonoBehaviour Lifecycle
+
+**Understanding Core MonoBehaviour Events:**
+
+```csharp
+// Example of a standard MonoBehaviour lifecycle
+using UnityEngine;
+
+public class PlayerController : MonoBehaviour
+{
+    // AWAKE: Called when the script instance is being loaded.
+    // Use for initialization before the game starts. Good for caching component references.
+    private void Awake()
+    {
+        Debug.Log("PlayerController Awake!");
+    }
+
+    // ONENABLE: Called when the object becomes enabled and active.
+    // Good for subscribing to events.
+    private void OnEnable()
+    {
+        // Example: UIManager.OnGamePaused += HandleGamePaused;
+    }
+
+    // START: Called on the frame when a script is enabled just before any of the Update methods are called the first time.
+    // Good for logic that depends on other objects being initialized.
+    private void Start()
+    {
+        Debug.Log("PlayerController Start!");
+    }
+
+    // FIXEDUPDATE: Called every fixed framerate frame.
+    // Use for physics calculations (e.g., applying forces to a Rigidbody).
+    private void FixedUpdate()
+    {
+        // Handle Rigidbody movement here.
+    }
+
+    // UPDATE: Called every frame.
+    // Use for most game logic, like handling input and non-physics movement.
+    private void Update()
+    {
+        // Handle input and non-physics movement here.
+    }
+
+    // LATEUPDATE: Called every frame, after all Update functions have been called.
+    // Good for camera logic that needs to track a target that moves in Update.
+    private void LateUpdate()
+    {
+        // Camera follow logic here.
+    }
+
+    // ONDISABLE: Called when the behaviour becomes disabled or inactive.
+    // Good for unsubscribing from events to prevent memory leaks.
+    private void OnDisable()
+    {
+        // Example: UIManager.OnGamePaused -= HandleGamePaused;
+    }
+
+    // ONDESTROY: Called when the MonoBehaviour will be destroyed.
+    // Good for any final cleanup.
+    private void OnDestroy()
+    {
+        Debug.Log("PlayerController Destroyed!");
+    }
+}
+```
+
+### Game Object Patterns
+
+**Component-Based Architecture:**
+
+```csharp
+// Player.cs - The main GameObject class, acts as a container for components.
+using UnityEngine;
+
+[RequireComponent(typeof(PlayerMovement), typeof(PlayerHealth))]
+public class Player : MonoBehaviour
+{
+    public PlayerMovement Movement { get; private set; }
+    public PlayerHealth Health { get; private set; }
+
+    private void Awake()
+    {
+        Movement = GetComponent<PlayerMovement>();
+        Health = GetComponent<PlayerHealth>();
+    }
+}
+
+// PlayerHealth.cs - A component responsible only for health logic.
+public class PlayerHealth : MonoBehaviour
+{
+    [SerializeField] private int _maxHealth = 100;
+    private int _currentHealth;
+
+    private void Awake()
+    {
+        _currentHealth = _maxHealth;
+    }
+
+    public void TakeDamage(int amount)
+    {
+        _currentHealth -= amount;
+        if (_currentHealth <= 0)
+        {
+            Die();
+        }
+    }
+
+    private void Die()
+    {
+        // Death logic
+        Debug.Log("Player has died.");
+        gameObject.SetActive(false);
+    }
+}
+```
+
+### Data-Driven Design with ScriptableObjects
+
+**Define Data Containers:**
+
+```csharp
+// EnemyData.cs - A ScriptableObject to hold data for an enemy type.
+using UnityEngine;
+
+[CreateAssetMenu(fileName = "NewEnemyData", menuName = "Game/Enemy Data")]
+public class EnemyData : ScriptableObject
+{
+    public string enemyName;
+    public int maxHealth;
+    public float moveSpeed;
+    public int damage;
+    public Sprite sprite;
+}
+
+// Enemy.cs - A MonoBehaviour that uses the EnemyData.
+public class Enemy : MonoBehaviour
+{
+    [SerializeField] private EnemyData _enemyData;
+    private int _currentHealth;
+
+    private void Start()
+    {
+        _currentHealth = _enemyData.maxHealth;
+        GetComponent<SpriteRenderer>().sprite = _enemyData.sprite;
+    }
+
+    // ... other enemy logic
+}
+```
+
+### System Management
+
+**Singleton Managers:**
+
+```csharp
+// GameManager.cs - A singleton to manage the overall game state.
+using UnityEngine;
+
+public class GameManager : MonoBehaviour
+{
+    public static GameManager Instance { get; private set; }
+
+    public int Score { get; private set; }
+
+    private void Awake()
+    {
+        if (Instance != null && Instance != this)
+        {
+            Destroy(gameObject);
+            return;
+        }
+        Instance = this;
+        DontDestroyOnLoad(gameObject); // Persist across scenes
+    }
+
+    public void AddScore(int amount)
+    {
+        Score += amount;
+    }
+}
+```
+
+## Performance Optimization
+
+### Object Pooling
+
+**Required for High-Frequency Objects (e.g., bullets, effects):**
+
+```csharp
+// ObjectPool.cs - A generic object pooling system.
+using UnityEngine;
+using System.Collections.Generic;
+
+public class ObjectPool : MonoBehaviour
+{
+    [SerializeField] private GameObject _prefabToPool;
+    [SerializeField] private int _initialPoolSize = 20;
+
+    private Queue<GameObject> _pool = new Queue<GameObject>();
+
+    private void Start()
+    {
+        for (int i = 0; i < _initialPoolSize; i++)
+        {
+            GameObject obj = Instantiate(_prefabToPool);
+            obj.SetActive(false);
+            _pool.Enqueue(obj);
+        }
+    }
+
+    public GameObject GetObjectFromPool()
+    {
+        if (_pool.Count > 0)
+        {
+            GameObject obj = _pool.Dequeue();
+            obj.SetActive(true);
+            return obj;
+        }
+        // Optionally, expand the pool if it's empty.
+        return Instantiate(_prefabToPool);
+    }
+
+    public void ReturnObjectToPool(GameObject obj)
+    {
+        obj.SetActive(false);
+        _pool.Enqueue(obj);
+    }
+}
+```
+
+### Frame Rate Optimization
+
+**Update Loop Optimization:**
+
+- Avoid expensive calls like `GetComponent`, `FindObjectOfType`, or `Instantiate` inside `Update()` or `FixedUpdate()`. Cache references in `Awake()` or `Start()`.
+- Use Coroutines or simple timers for logic that doesn't need to run every single frame.
+
+**Physics Optimization:**
+
+- Adjust the "Physics 2D Settings" in Project Settings, especially the "Layer Collision Matrix", to prevent unnecessary collision checks.
+- Use `Rigidbody2D.Sleep()` for objects that are not moving to save CPU cycles.
+
+## Input Handling
+
+### Cross-Platform Input (New Input System)
+
+**Input Action Asset:** Create an Input Action Asset (`.inputactions`) to define controls.
+
+**PlayerInput Component:**
+
+- Add the `PlayerInput` component to the player GameObject.
+- Set its "Actions" to the created Input Action Asset.
+- Set "Behavior" to "Invoke Unity Events" to easily hook up methods in the Inspector, or "Send Messages" to use methods like `OnMove`, `OnFire`.
+
+```csharp
+// PlayerInputHandler.cs - Example of handling input via messages.
+using UnityEngine;
+using UnityEngine.InputSystem;
+
+public class PlayerInputHandler : MonoBehaviour
+{
+    private Vector2 _moveInput;
+
+    // This method is called by the PlayerInput component via "Send Messages".
+    // The action must be named "Move" in the Input Action Asset.
+    public void OnMove(InputValue value)
+    {
+        _moveInput = value.Get<Vector2>();
+    }
+
+    private void Update()
+    {
+        // Use _moveInput to control the player
+        transform.Translate(new Vector3(_moveInput.x, _moveInput.y, 0) * Time.deltaTime * 5f);
+    }
+}
+```
+
+## Error Handling
+
+### Graceful Degradation
+
+**Asset Loading Error Handling:**
+
+- When using Addressables or `Resources.Load`, always check if the loaded asset is null before using it.
+
+```csharp
+// Load a sprite and use a fallback if it fails
+Sprite playerSprite = Resources.Load<Sprite>("Sprites/Player");
+if (playerSprite == null)
+{
+    Debug.LogError("Player sprite not found! Using default.");
+    playerSprite = Resources.Load<Sprite>("Sprites/Default");
+}
+```
+
+### Runtime Error Recovery
+
+**Assertions and Logging:**
+
+- Use `Debug.Assert(condition, "Message")` to check for critical conditions that must be true.
+- Use `Debug.LogError("Message")` for fatal errors and `Debug.LogWarning("Message")` for non-critical issues.
+
+```csharp
+// Example of using an assertion to ensure a component exists.
+private Rigidbody2D _rb;
+
+void Awake()
+{
+    _rb = GetComponent<Rigidbody2D>();
+    Debug.Assert(_rb != null, "Rigidbody2D component not found on player!");
+}
+```
+
+## Testing Standards
+
+### Unit Testing (Edit Mode)
+
+**Game Logic Testing:**
+
+```csharp
+// HealthSystemTests.cs - Example test for a simple health system.
+using NUnit.Framework;
+using UnityEngine;
+
+public class HealthSystemTests
+{
+    [Test]
+    public void TakeDamage_ReducesHealth()
+    {
+        // Arrange
+        var gameObject = new GameObject();
+        var healthSystem = gameObject.AddComponent<PlayerHealth>();
+        // Note: This is a simplified example. You might need to mock dependencies.
+
+        // Act
+        healthSystem.TakeDamage(20);
+
+        // Assert
+        // This requires making health accessible for testing, e.g., via a public property or method.
+        // Assert.AreEqual(80, healthSystem.CurrentHealth);
+    }
+}
+```
+
+### Integration Testing (Play Mode)
+
+**Scene Testing:**
+
+- Play Mode tests run in a live scene, allowing you to test interactions between multiple components and systems.
+- Use `yield return null;` to wait for the next frame.
+
+```csharp
+// PlayerJumpTest.cs
+using System.Collections;
+using NUnit.Framework;
+using UnityEngine;
+using UnityEngine.TestTools;
+
+public class PlayerJumpTest
+{
+    [UnityTest]
+    public IEnumerator PlayerJumps_WhenSpaceIsPressed()
+    {
+        // Arrange
+        var player = new GameObject().AddComponent<PlayerController>();
+        var initialY = player.transform.position.y;
+
+        // Act
+        // Simulate pressing the jump button (requires setting up the input system for tests)
+        // For simplicity, we'll call a public method here.
+        // player.Jump();
+
+        // Wait for a few physics frames
+        yield return new WaitForSeconds(0.5f);
+
+        // Assert
+        Assert.Greater(player.transform.position.y, initialY);
+    }
+}
+```
+
+## File Organization
+
+### Project Structure
+
+```
+Assets/
+├── Scenes/
+│   ├── MainMenu.unity
+│   └── Level01.unity
+├── Scripts/
+│   ├── Core/
+│   │   ├── GameManager.cs
+│   │   └── AudioManager.cs
+│   ├── Player/
+│   │   ├── PlayerController.cs
+│   │   └── PlayerHealth.cs
+│   ├── Editor/
+│   │   └── CustomInspectors.cs
+│   └── Data/
+│       └── EnemyData.cs
+├── Prefabs/
+│   ├── Player.prefab
+│   └── Enemies/
+│       └── Slime.prefab
+├── Art/
+│   ├── Sprites/
+│   └── Animations/
+├── Audio/
+│   ├── Music/
+│   └── SFX/
+├── Data/
+│   └── ScriptableObjects/
+│       └── EnemyData/
+└── Tests/
+    ├── EditMode/
+    │   └── HealthSystemTests.cs
+    └── PlayMode/
+        └── PlayerJumpTest.cs
+```
+
+## Development Workflow
+
+### Story Implementation Process
+
+1. **Read Story Requirements:**
+
+   - Understand acceptance criteria
+   - Identify technical requirements
+   - Review performance constraints
+
+2. **Plan Implementation:**
+
+   - Identify files to create/modify
+   - Consider Unity's component-based architecture
+   - Plan testing approach
+
+3. **Implement Feature:**
+
+   - Write clean C# code following all guidelines
+   - Use established patterns
+   - Maintain stable FPS performance
+
+4. **Test Implementation:**
+
+   - Write edit mode tests for game logic
+   - Write play mode tests for integration testing
+   - Test cross-platform functionality
+   - Validate performance targets
+
+5. **Update Documentation:**
+   - Mark story checkboxes complete
+   - Document any deviations
+   - Update architecture if needed
+
+### Code Review Checklist
+
+- [ ] C# code compiles without errors or warnings.
+- [ ] All automated tests pass.
+- [ ] Code follows naming conventions and architectural patterns.
+- [ ] No expensive operations in `Update()` loops.
+- [ ] Public fields/methods are documented with comments.
+- [ ] New assets are organized into the correct folders.
+
+## Performance Targets
+
+### Frame Rate Requirements
+
+- **PC/Console**: Maintain a stable 60+ FPS.
+- **Mobile**: Maintain 60 FPS on mid-range devices, minimum 30 FPS on low-end.
+- **Optimization**: Use the Unity Profiler to identify and fix performance drops.
+
+### Memory Management
+
+- **Total Memory**: Keep builds under platform-specific limits (e.g., 200MB for a simple mobile game).
+- **Garbage Collection**: Minimize GC spikes by avoiding string concatenation, `new` keyword usage in loops, and by pooling objects.
+
+### Loading Performance
+
+- **Initial Load**: Under 5 seconds for game start.
+- **Scene Transitions**: Under 2 seconds between scenes. Use asynchronous scene loading.
+
+These guidelines ensure consistent, high-quality game development that meets performance targets and maintains code quality across all implementation stories.

package/#Tools/APPIQ-METHOD/expansion-packs/bmad-2d-unity-game-dev/tasks/advanced-elicitation.md

@@ -0,0 +1,111 @@
+# Advanced Game Design Elicitation Task
+
+## Purpose
+
+- Provide optional reflective and brainstorming actions to enhance game design content quality
+- Enable deeper exploration of game mechanics and player experience through structured elicitation techniques
+- Support iterative refinement through multiple game development perspectives
+- Apply game-specific critical thinking to design decisions
+
+## Task Instructions
+
+### 1. Game Design Context and Review
+
+[[LLM: When invoked after outputting a game design section:
+
+1. First, provide a brief 1-2 sentence summary of what the user should look for in the section just presented, with game-specific focus (e.g., "Please review the core mechanics for player engagement and implementation feasibility. Pay special attention to how these mechanics create the intended player experience and whether they're technically achievable with Unity.")
+
+2. If the section contains game flow diagrams, level layouts, or system diagrams, explain each diagram briefly with game development context before offering elicitation options (e.g., "The gameplay loop diagram shows how player actions lead to rewards and progression. Notice how each step maintains player engagement and creates opportunities for skill development.")
+
+3. If the section contains multiple game elements (like multiple mechanics, multiple levels, multiple systems, etc.), inform the user they can apply elicitation actions to:
+
+   - The entire section as a whole
+   - Individual game elements within the section (specify which element when selecting an action)
+
+4. Then present the action list as specified below.]]
+
+### 2. Ask for Review and Present Game Design Action List
+
+[[LLM: Ask the user to review the drafted game design section. In the SAME message, inform them that they can suggest additions, removals, or modifications, OR they can select an action by number from the 'Advanced Game Design Elicitation & Brainstorming Actions'. If there are multiple game elements in the section, mention they can specify which element(s) to apply the action to. Then, present ONLY the numbered list (0-9) of these actions. Conclude by stating that selecting 9 will proceed to the next section. Await user selection. If an elicitation action (0-8) is chosen, execute it and then re-offer this combined review/elicitation choice. If option 9 is chosen, or if the user provides direct feedback, proceed accordingly.]]
+
+**Present the numbered list (0-9) with this exact format:**
+
+```text
+**Advanced Game Design Elicitation & Brainstorming Actions**
+Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
+
+0. Expand or Contract for Target Audience
+1. Explain Game Design Reasoning (Step-by-Step)
+2. Critique and Refine from Player Perspective
+3. Analyze Game Flow and Mechanic Dependencies
+4. Assess Alignment with Player Experience Goals
+5. Identify Potential Player Confusion and Design Risks
+6. Challenge from Critical Game Design Perspective
+7. Explore Alternative Game Design Approaches
+8. Hindsight Postmortem: The 'If Only...' Game Design Reflection
+9. Proceed / No Further Actions
+```
+
+### 2. Processing Guidelines
+
+**Do NOT show:**
+
+- The full protocol text with `[[LLM: ...]]` instructions
+- Detailed explanations of each option unless executing or the user asks, when giving the definition you can modify to tie its game development relevance
+- Any internal template markup
+
+**After user selection from the list:**
+
+- Execute the chosen action according to the game design protocol instructions below
+- Ask if they want to select another action or proceed with option 9 once complete
+- Continue until user selects option 9 or indicates completion
+
+## Game Design Action Definitions
+
+0. Expand or Contract for Target Audience
+   [[LLM: Ask the user whether they want to 'expand' on the game design content (add more detail, elaborate on mechanics, include more examples) or 'contract' it (simplify mechanics, focus on core features, reduce complexity). Also, ask if there's a specific player demographic or experience level they have in mind (casual players, hardcore gamers, children, etc.). Once clarified, perform the expansion or contraction from your current game design role's perspective, tailored to the specified player audience if provided.]]
+
+1. Explain Game Design Reasoning (Step-by-Step)
+   [[LLM: Explain the step-by-step game design thinking process that you used to arrive at the current proposal for this game content. Focus on player psychology, engagement mechanics, technical feasibility, and how design decisions support the overall player experience goals.]]
+
+2. Critique and Refine from Player Perspective
+   [[LLM: From your current game design role's perspective, review your last output or the current section for potential player confusion, engagement issues, balance problems, or areas for improvement. Consider how players will actually interact with and experience these systems, then suggest a refined version that better serves player enjoyment and understanding.]]
+
+3. Analyze Game Flow and Mechanic Dependencies
+   [[LLM: From your game design role's standpoint, examine the content's structure for logical gameplay progression, mechanic interdependencies, and player learning curve. Confirm if game elements are introduced in an effective order that teaches players naturally and maintains engagement throughout the experience.]]
+
+4. Assess Alignment with Player Experience Goals
+   [[LLM: Evaluate how well the current game design content contributes to the stated player experience goals and core game pillars. Consider whether the mechanics actually create the intended emotions and engagement patterns. Identify any misalignments between design intentions and likely player reactions.]]
+
+5. Identify Potential Player Confusion and Design Risks
+   [[LLM: Based on your game design expertise, brainstorm potential sources of player confusion, overlooked edge cases in gameplay, balance issues, technical implementation risks, or unintended player behaviors that could emerge from the current design. Consider both new and experienced players' perspectives.]]
+
+6. Challenge from Critical Game Design Perspective
+   [[LLM: Adopt a critical game design perspective on the current content. If the user specifies another viewpoint (e.g., 'as a casual player', 'as a speedrunner', 'as a mobile player', 'as a technical implementer'), critique the content from that specified perspective. If no other role is specified, play devil's advocate from your game design expertise, arguing against the current design proposal and highlighting potential weaknesses, player experience issues, or implementation challenges. This can include questioning scope creep, unnecessary complexity, or features that don't serve the core player experience.]]
+
+7. Explore Alternative Game Design Approaches
+   [[LLM: From your game design role's perspective, first broadly brainstorm a range of diverse approaches to achieving the same player experience goals or solving the same design challenge. Consider different genres, mechanics, interaction models, or technical approaches. Then, from this wider exploration, select and present 2-3 distinct alternative design approaches, detailing the pros, cons, player experience implications, and technical feasibility you foresee for each.]]
+
+8. Hindsight Postmortem: The 'If Only...' Game Design Reflection
+   [[LLM: In your current game design persona, imagine this is a postmortem for a shipped game based on the current design content. What's the one 'if only we had designed/considered/tested X...' that your role would highlight from a game design perspective? Include the imagined player reactions, review scores, or development consequences. This should be both insightful and somewhat humorous, focusing on common game design pitfalls.]]
+
+9. Proceed / No Further Actions
+   [[LLM: Acknowledge the user's choice to finalize the current game design work, accept the AI's last output as is, or move on to the next step without selecting another action from this list. Prepare to proceed accordingly.]]
+
+## Game Development Context Integration
+
+This elicitation task is specifically designed for game development and should be used in contexts where:
+
+- **Game Mechanics Design**: When defining core gameplay systems and player interactions
+- **Player Experience Planning**: When designing for specific emotional responses and engagement patterns
+- **Technical Game Architecture**: When balancing design ambitions with implementation realities
+- **Game Balance and Progression**: When designing difficulty curves and player advancement systems
+- **Platform Considerations**: When adapting designs for different devices and input methods
+
+The questions and perspectives offered should always consider:
+
+- Player psychology and motivation
+- Technical feasibility with Unity and C#
+- Performance implications for stable frame rate targets
+- Cross-platform compatibility (PC, console, mobile)
+- Game development best practices and common pitfalls