bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.21

package/src/modules/bmgd/gametest/knowledge/input-testing.md

@@ -0,0 +1,315 @@
+# Input Testing Guide
+
+## Overview
+
+Input testing validates that all supported input devices work correctly across platforms. Poor input handling frustrates players instantly—responsive, accurate input is foundational to game feel.
+
+## Input Categories
+
+### Device Types
+
+| Device            | Platforms      | Key Concerns                        |
+| ----------------- | -------------- | ----------------------------------- |
+| Keyboard + Mouse  | PC             | Key conflicts, DPI sensitivity      |
+| Gamepad (Xbox/PS) | PC, Console    | Deadzone, vibration, button prompts |
+| Touch             | Mobile, Switch | Multi-touch, gesture recognition    |
+| Motion Controls   | Switch, VR     | Calibration, drift, fatigue         |
+| Specialty         | Various        | Flight sticks, wheels, fight sticks |
+
+### Input Characteristics
+
+| Characteristic | Description                  | Test Focus                       |
+| -------------- | ---------------------------- | -------------------------------- |
+| Responsiveness | Input-to-action delay        | Should feel instant (< 100ms)    |
+| Accuracy       | Input maps to correct action | No ghost inputs or missed inputs |
+| Consistency    | Same input = same result     | Deterministic behavior           |
+| Accessibility  | Alternative input support    | Remapping, assist options        |
+
+## Test Scenarios
+
+### Keyboard and Mouse
+
+```
+SCENARIO: All Keybinds Functional
+  GIVEN default keyboard bindings
+  WHEN each bound key is pressed
+  THEN corresponding action triggers
+  AND no key conflicts exist
+
+SCENARIO: Key Remapping
+  GIVEN player remaps "Jump" from Space to F
+  WHEN F is pressed
+  THEN jump action triggers
+  AND Space no longer triggers jump
+  AND remapping persists after restart
+
+SCENARIO: Mouse Sensitivity
+  GIVEN sensitivity set to 5 (mid-range)
+  WHEN mouse moves 10cm
+  THEN camera rotation matches expected degrees
+  AND movement feels consistent at different frame rates
+
+SCENARIO: Mouse Button Support
+  GIVEN mouse with 5+ buttons
+  WHEN side buttons are pressed
+  THEN they can be bound to actions
+  AND they function correctly in gameplay
+```
+
+### Gamepad
+
+```
+SCENARIO: Analog Stick Deadzone
+  GIVEN controller with slight stick drift
+  WHEN stick is in neutral position
+  THEN no movement occurs (deadzone filters drift)
+  AND intentional small movements still register
+
+SCENARIO: Trigger Pressure
+  GIVEN analog triggers
+  WHEN trigger is partially pressed
+  THEN partial values are read (e.g., 0.5 for half-press)
+  AND full press reaches 1.0
+
+SCENARIO: Controller Hot-Swap
+  GIVEN game running with keyboard
+  WHEN gamepad is connected
+  THEN input prompts switch to gamepad icons
+  AND gamepad input works immediately
+  AND keyboard still works if used
+
+SCENARIO: Vibration Feedback
+  GIVEN rumble-enabled controller
+  WHEN damage is taken
+  THEN controller vibrates appropriately
+  AND vibration intensity matches damage severity
+```
+
+### Touch Input
+
+```
+SCENARIO: Multi-Touch Accuracy
+  GIVEN virtual joystick and buttons
+  WHEN left thumb on joystick AND right thumb on button
+  THEN both inputs register simultaneously
+  AND no interference between touch points
+
+SCENARIO: Gesture Recognition
+  GIVEN swipe-to-attack mechanic
+  WHEN player swipes right
+  THEN attack direction matches swipe
+  AND swipe is distinguished from tap
+
+SCENARIO: Touch Target Size
+  GIVEN minimum touch target of 44x44 points
+  WHEN buttons are placed
+  THEN all interactive elements meet minimum size
+  AND elements have adequate spacing
+```
+
+## Platform-Specific Testing
+
+### PC
+
+- Multiple keyboard layouts (QWERTY, AZERTY, QWERTZ)
+- Different mouse DPI settings (400-3200+)
+- Multiple monitors (cursor confinement)
+- Background application conflicts
+- Steam Input API integration
+
+### Console
+
+| Platform    | Specific Tests                             |
+| ----------- | ------------------------------------------ |
+| PlayStation | Touchpad, adaptive triggers, haptics       |
+| Xbox        | Impulse triggers, Elite controller paddles |
+| Switch      | Joy-Con detachment, gyro, HD rumble        |
+
+### Mobile
+
+- Different screen sizes and aspect ratios
+- Notch/cutout avoidance
+- External controller support
+- Apple MFi / Android gamepad compatibility
+
+## Automated Test Examples
+
+### Unity
+
+```csharp
+using UnityEngine.InputSystem;
+
+[UnityTest]
+public IEnumerator Movement_WithGamepad_RespondsToStick()
+{
+    var gamepad = InputSystem.AddDevice<Gamepad>();
+
+    yield return null;
+
+    // Simulate stick input
+    Set(gamepad.leftStick, new Vector2(1, 0));
+    yield return new WaitForSeconds(0.1f);
+
+    Assert.Greater(player.transform.position.x, 0f,
+        "Player should move right");
+
+    InputSystem.RemoveDevice(gamepad);
+}
+
+[UnityTest]
+public IEnumerator InputLatency_UnderLoad_StaysAcceptable()
+{
+    float inputTime = Time.realtimeSinceStartup;
+    bool actionTriggered = false;
+
+    player.OnJump += () => {
+        float latency = (Time.realtimeSinceStartup - inputTime) * 1000;
+        Assert.Less(latency, 100f, "Input latency should be under 100ms");
+        actionTriggered = true;
+    };
+
+    var keyboard = InputSystem.AddDevice<Keyboard>();
+    Press(keyboard.spaceKey);
+
+    yield return new WaitForSeconds(0.2f);
+
+    Assert.IsTrue(actionTriggered, "Jump should have triggered");
+}
+
+[Test]
+public void Deadzone_FiltersSmallInputs()
+{
+    var settings = new InputSettings { stickDeadzone = 0.2f };
+
+    // Input below deadzone
+    var filtered = InputProcessor.ApplyDeadzone(new Vector2(0.1f, 0.1f), settings);
+    Assert.AreEqual(Vector2.zero, filtered);
+
+    // Input above deadzone
+    filtered = InputProcessor.ApplyDeadzone(new Vector2(0.5f, 0.5f), settings);
+    Assert.AreNotEqual(Vector2.zero, filtered);
+}
+```
+
+### Unreal
+
+```cpp
+bool FInputTest::RunTest(const FString& Parameters)
+{
+    // Test gamepad input mapping
+    APlayerController* PC = GetWorld()->GetFirstPlayerController();
+
+    // Simulate gamepad stick input
+    FInputKeyParams Params;
+    Params.Key = EKeys::Gamepad_LeftX;
+    Params.Delta = FVector(1.0f, 0, 0);
+    PC->InputKey(Params);
+
+    // Verify movement
+    APawn* Pawn = PC->GetPawn();
+    FVector Velocity = Pawn->GetVelocity();
+
+    TestTrue("Pawn should be moving", Velocity.SizeSquared() > 0);
+
+    return true;
+}
+```
+
+### Godot
+
+```gdscript
+func test_input_action_mapping():
+    # Verify action exists
+    assert_true(InputMap.has_action("jump"))
+
+    # Simulate input
+    var event = InputEventKey.new()
+    event.keycode = KEY_SPACE
+    event.pressed = true
+
+    Input.parse_input_event(event)
+    await get_tree().process_frame
+
+    assert_true(Input.is_action_just_pressed("jump"))
+
+func test_gamepad_deadzone():
+    var input = Vector2(0.15, 0.1)
+    var deadzone = 0.2
+
+    var processed = input_processor.apply_deadzone(input, deadzone)
+
+    assert_eq(processed, Vector2.ZERO, "Small input should be filtered")
+
+func test_controller_hotswap():
+    # Simulate controller connect
+    Input.joy_connection_changed(0, true)
+    await get_tree().process_frame
+
+    var prompt_icon = ui.get_action_prompt("jump")
+
+    assert_true(prompt_icon.texture.resource_path.contains("gamepad"),
+        "Should show gamepad prompts after controller connect")
+```
+
+## Accessibility Testing
+
+### Requirements Checklist
+
+- [ ] Full keyboard navigation (no mouse required)
+- [ ] Remappable controls for all actions
+- [ ] Button hold alternatives to rapid press
+- [ ] Toggle options for hold actions
+- [ ] One-handed control schemes
+- [ ] Colorblind-friendly UI indicators
+- [ ] Screen reader support for menus
+
+### Accessibility Test Scenarios
+
+```
+SCENARIO: Keyboard-Only Navigation
+  GIVEN mouse is disconnected
+  WHEN navigating through all menus
+  THEN all menu items are reachable via keyboard
+  AND focus indicators are clearly visible
+
+SCENARIO: Button Hold Toggle
+  GIVEN "sprint requires hold" is toggled OFF
+  WHEN sprint button is tapped once
+  THEN sprint activates
+  AND sprint stays active until tapped again
+
+SCENARIO: Reduced Button Mashing
+  GIVEN QTE assist mode enabled
+  WHEN QTE sequence appears
+  THEN single press advances sequence
+  AND no rapid input required
+```
+
+## Performance Metrics
+
+| Metric                  | Target          | Maximum Acceptable |
+| ----------------------- | --------------- | ------------------ |
+| Input-to-render latency | < 50ms          | 100ms              |
+| Polling rate match      | 1:1 with device | No input loss      |
+| Deadzone processing     | < 1ms           | 5ms                |
+| Rebind save/load        | < 100ms         | 500ms              |
+
+## Best Practices
+
+### DO
+
+- Test with actual hardware, not just simulated input
+- Support simultaneous keyboard + gamepad
+- Provide sensible default deadzones
+- Show device-appropriate button prompts
+- Allow complete control remapping
+- Test at different frame rates
+
+### DON'T
+
+- Assume controller layout (Xbox vs PlayStation)
+- Hard-code input mappings
+- Ignore analog input precision
+- Skip accessibility considerations
+- Forget about input during loading/cutscenes
+- Neglect testing with worn/drifting controllers

package/src/modules/bmgd/gametest/knowledge/localization-testing.md

@@ -0,0 +1,304 @@
+# Localization Testing Guide
+
+## Overview
+
+Localization testing ensures games work correctly across languages, regions, and cultures. Beyond translation, it validates text display, cultural appropriateness, and regional compliance.
+
+## Test Categories
+
+### Linguistic Testing
+
+| Category             | Focus                   | Examples                       |
+| -------------------- | ----------------------- | ------------------------------ |
+| Translation accuracy | Meaning preserved       | Idioms, game terminology       |
+| Grammar/spelling     | Language correctness    | Verb tense, punctuation        |
+| Consistency          | Same terms throughout   | "Health" vs "HP" vs "Life"     |
+| Context              | Meaning in game context | Item names, skill descriptions |
+
+### Functional Testing
+
+| Category       | Focus                   | Examples                    |
+| -------------- | ----------------------- | --------------------------- |
+| Text display   | Fits in UI              | Button labels, dialog boxes |
+| Font support   | Characters render       | CJK, Cyrillic, Arabic       |
+| Text expansion | Longer translations     | German is ~30% longer       |
+| RTL support    | Right-to-left languages | Arabic, Hebrew layouts      |
+
+### Cultural Testing
+
+| Category             | Focus              | Examples                  |
+| -------------------- | ------------------ | ------------------------- |
+| Cultural sensitivity | Offensive content  | Gestures, symbols, colors |
+| Regional compliance  | Legal requirements | Ratings, gambling laws    |
+| Date/time formats    | Local conventions  | DD/MM/YYYY vs MM/DD/YYYY  |
+| Number formats       | Decimal separators | 1,000.00 vs 1.000,00      |
+
+## Test Scenarios
+
+### Text Display
+
+```
+SCENARIO: Text Fits UI Elements
+  GIVEN all localized strings
+  WHEN displayed in target language
+  THEN text fits within UI boundaries
+  AND no truncation or overflow occurs
+  AND text remains readable
+
+SCENARIO: Dynamic Text Insertion
+  GIVEN template "Player {name} scored {points} points"
+  WHEN name="Alexander" and points=1000
+  THEN German: "Spieler Alexander hat 1.000 Punkte erzielt"
+  AND text fits UI element
+  AND variables are correctly formatted for locale
+
+SCENARIO: Plural Forms
+  GIVEN English "1 coin" / "5 coins"
+  WHEN displaying in Polish (4 plural forms)
+  THEN correct plural form is used
+  AND all plural forms are translated
+```
+
+### Character Support
+
+```
+SCENARIO: CJK Character Rendering
+  GIVEN Japanese localization
+  WHEN displaying text with kanji/hiragana/katakana
+  THEN all characters render correctly
+  AND no missing glyphs (tofu boxes)
+  AND line breaks respect CJK rules
+
+SCENARIO: Special Characters
+  GIVEN text with accented characters (é, ñ, ü)
+  WHEN displayed in-game
+  THEN all characters render correctly
+  AND sorting works correctly
+
+SCENARIO: User-Generated Content
+  GIVEN player can name character
+  WHEN name includes non-Latin characters
+  THEN name displays correctly
+  AND name saves/loads correctly
+  AND name appears correctly to other players
+```
+
+### Layout and Direction
+
+```
+SCENARIO: Right-to-Left Layout
+  GIVEN Arabic localization
+  WHEN viewing UI
+  THEN text reads right-to-left
+  AND UI elements mirror appropriately
+  AND numbers remain left-to-right
+  AND mixed content (Arabic + English) displays correctly
+
+SCENARIO: Text Expansion Accommodation
+  GIVEN English UI "OK" / "Cancel" buttons
+  WHEN localized to German "OK" / "Abbrechen"
+  THEN button expands or text size adjusts
+  AND button remains clickable
+  AND layout doesn't break
+```
+
+## Locale-Specific Formatting
+
+### Date and Time
+
+| Locale | Date Format    | Time Format |
+| ------ | -------------- | ----------- |
+| en-US  | 12/25/2024     | 3:30 PM     |
+| en-GB  | 25/12/2024     | 15:30       |
+| de-DE  | 25.12.2024     | 15:30 Uhr   |
+| ja-JP  | 2024年12月25日 | 15時30分    |
+
+### Numbers and Currency
+
+| Locale | Number   | Currency   |
+| ------ | -------- | ---------- |
+| en-US  | 1,234.56 | $1,234.56  |
+| de-DE  | 1.234,56 | 1.234,56 € |
+| fr-FR  | 1 234,56 | 1 234,56 € |
+| ja-JP  | 1,234.56 | ¥1,235     |
+
+## Automated Test Examples
+
+### Unity
+
+```csharp
+using UnityEngine.Localization;
+
+[Test]
+public void Localization_AllKeysHaveTranslations([Values("en", "de", "ja", "zh-CN")] string locale)
+{
+    var stringTable = LocalizationSettings.StringDatabase
+        .GetTable("GameStrings", new Locale(locale));
+
+    foreach (var entry in stringTable)
+    {
+        Assert.IsFalse(string.IsNullOrEmpty(entry.Value.LocalizedValue),
+            $"Missing translation for '{entry.Key}' in {locale}");
+    }
+}
+
+[Test]
+public void TextFits_AllUIElements()
+{
+    var languages = new[] { "en", "de", "fr", "ja" };
+
+    foreach (var lang in languages)
+    {
+        LocalizationSettings.SelectedLocale = new Locale(lang);
+
+        foreach (var textElement in FindObjectsOfType<LocalizedText>())
+        {
+            var rectTransform = textElement.GetComponent<RectTransform>();
+            var textComponent = textElement.GetComponent<Text>();
+
+            Assert.LessOrEqual(
+                textComponent.preferredWidth,
+                rectTransform.rect.width,
+                $"Text overflows in {lang}: {textElement.name}");
+        }
+    }
+}
+
+[TestCase("en", 1, "1 coin")]
+[TestCase("en", 5, "5 coins")]
+[TestCase("ru", 1, "1 монета")]
+[TestCase("ru", 2, "2 монеты")]
+[TestCase("ru", 5, "5 монет")]
+public void Pluralization_ReturnsCorrectForm(string locale, int count, string expected)
+{
+    var result = Localization.GetPlural("coin", count, locale);
+    Assert.AreEqual(expected, result);
+}
+```
+
+### Unreal
+
+```cpp
+bool FLocalizationTest::RunTest(const FString& Parameters)
+{
+    TArray<FString> Cultures = {"en", "de", "ja", "ko"};
+
+    for (const FString& Culture : Cultures)
+    {
+        FInternationalization::Get().SetCurrentCulture(Culture);
+
+        // Test critical strings exist
+        FText LocalizedText = NSLOCTEXT("Game", "StartButton", "Start");
+        TestFalse(
+            FString::Printf(TEXT("Missing StartButton in %s"), *Culture),
+            LocalizedText.IsEmpty());
+
+        // Test number formatting
+        FText NumberText = FText::AsNumber(1234567);
+        TestTrue(
+            TEXT("Number should be formatted"),
+            NumberText.ToString().Len() > 7); // Has separators
+    }
+
+    return true;
+}
+```
+
+### Godot
+
+```gdscript
+func test_all_translations_complete():
+    var locales = ["en", "de", "ja", "es"]
+    var keys = TranslationServer.get_all_keys()
+
+    for locale in locales:
+        TranslationServer.set_locale(locale)
+        for key in keys:
+            var translated = tr(key)
+            assert_ne(translated, key,
+                "Missing translation for '%s' in %s" % [key, locale])
+
+func test_plural_forms():
+    TranslationServer.set_locale("ru")
+
+    assert_eq(tr_n("coin", "coins", 1), "1 монета")
+    assert_eq(tr_n("coin", "coins", 2), "2 монеты")
+    assert_eq(tr_n("coin", "coins", 5), "5 монет")
+    assert_eq(tr_n("coin", "coins", 21), "21 монета")
+
+func test_text_fits_buttons():
+    var locales = ["en", "de", "fr"]
+
+    for locale in locales:
+        TranslationServer.set_locale(locale)
+        await get_tree().process_frame  # Allow UI update
+
+        for button in get_tree().get_nodes_in_group("localized_buttons"):
+            var label = button.get_node("Label")
+            assert_lt(label.size.x, button.size.x,
+                "Button text overflows in %s: %s" % [locale, button.name])
+```
+
+## Visual Verification Checklist
+
+### Text Display
+
+- [ ] No truncation in any language
+- [ ] Consistent font sizing
+- [ ] Proper line breaks
+- [ ] No overlapping text
+
+### UI Layout
+
+- [ ] Buttons accommodate longer text
+- [ ] Dialog boxes resize appropriately
+- [ ] Menu items align correctly
+- [ ] Scrollbars appear when needed
+
+### Cultural Elements
+
+- [ ] Icons are culturally appropriate
+- [ ] Colors don't have negative connotations
+- [ ] Gestures are region-appropriate
+- [ ] No unintended political references
+
+## Regional Compliance
+
+### Ratings Requirements
+
+| Region        | Rating Board | Special Requirements      |
+| ------------- | ------------ | ------------------------- |
+| North America | ESRB         | Content descriptors       |
+| Europe        | PEGI         | Age-appropriate icons     |
+| Japan         | CERO         | Strict content guidelines |
+| Germany       | USK          | Violence restrictions     |
+| China         | GRAC         | Approval process          |
+
+### Common Regional Issues
+
+| Issue            | Regions Affected | Solution                 |
+| ---------------- | ---------------- | ------------------------ |
+| Blood color      | Japan, Germany   | Option for green/disable |
+| Gambling imagery | Many regions     | Remove or modify         |
+| Skulls/bones     | China            | Alternative designs      |
+| Nazi imagery     | Germany          | Remove entirely          |
+
+## Best Practices
+
+### DO
+
+- Test with native speakers
+- Plan for text expansion (reserve 30% extra space)
+- Use placeholder text during development (Lorem ipsum-style)
+- Support multiple input methods (IME for CJK)
+- Test all language combinations (UI language + audio language)
+- Validate string format parameters
+
+### DON'T
+
+- Hard-code strings in source code
+- Assume left-to-right layout
+- Concatenate translated strings
+- Use machine translation without review
+- Forget about date/time/number formatting
+- Ignore cultural context of images and icons