bmad-method 6.0.0-alpha.17 → 6.0.0-alpha.18

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

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

@@ -0,0 +1,322 @@
+# Multiplayer Testing Guide
+
+## Overview
+
+Multiplayer testing validates network code, synchronization, and the player experience under real-world conditions. Network bugs are notoriously hard to reproduce—systematic testing is essential.
+
+## Test Categories
+
+### Synchronization Testing
+
+| Test Type           | Description                              | Priority |
+| ------------------- | ---------------------------------------- | -------- |
+| State sync          | All clients see consistent game state    | P0       |
+| Position sync       | Character positions match across clients | P0       |
+| Event ordering      | Actions occur in correct sequence        | P0       |
+| Conflict resolution | Simultaneous actions handled correctly   | P1       |
+| Late join           | New players sync correctly mid-game      | P1       |
+
+### Network Conditions
+
+| Condition       | Simulation Method | Test Focus               |
+| --------------- | ----------------- | ------------------------ |
+| High latency    | 200-500ms delay   | Input responsiveness     |
+| Packet loss     | 5-20% drop rate   | State recovery           |
+| Jitter          | Variable delay    | Interpolation smoothness |
+| Bandwidth limit | Throttle to 1Mbps | Data prioritization      |
+| Disconnection   | Kill connection   | Reconnection handling    |
+
+## Test Scenarios
+
+### Basic Multiplayer
+
+```
+SCENARIO: Player Join/Leave
+  GIVEN host has started multiplayer session
+  WHEN Player 2 joins
+  THEN Player 2 appears in host's game
+  AND Player 1 appears in Player 2's game
+  AND player counts sync across all clients
+
+SCENARIO: State Synchronization
+  GIVEN 4 players in match
+  WHEN Player 1 picks up item at position (10, 5)
+  THEN item disappears for all players
+  AND Player 1's inventory updates for all players
+  AND no duplicate pickups possible
+
+SCENARIO: Combat Synchronization
+  GIVEN Player 1 attacks Player 2
+  WHEN attack hits
+  THEN damage is consistent on all clients
+  AND hit effects play for all players
+  AND health updates sync within 100ms
+```
+
+### Network Degradation
+
+```
+SCENARIO: High Latency Gameplay
+  GIVEN 200ms latency between players
+  WHEN Player 1 moves forward
+  THEN movement is smooth on Player 1's screen
+  AND other players see interpolated movement
+  AND position converges within 500ms
+
+SCENARIO: Packet Loss Recovery
+  GIVEN 10% packet loss
+  WHEN important game event occurs (goal, kill, etc.)
+  THEN event is eventually delivered
+  AND game state remains consistent
+  AND no duplicate events processed
+
+SCENARIO: Player Disconnection
+  GIVEN Player 2 disconnects unexpectedly
+  WHEN 5 seconds pass
+  THEN other players are notified
+  AND Player 2's character handles gracefully (despawn/AI takeover)
+  AND game continues without crash
+```
+
+### Edge Cases
+
+```
+SCENARIO: Simultaneous Actions
+  GIVEN Player 1 and Player 2 grab same item simultaneously
+  WHEN both inputs arrive at server
+  THEN only one player receives item
+  AND other player sees consistent state
+  AND no item duplication
+
+SCENARIO: Host Migration
+  GIVEN host disconnects
+  WHEN migration begins
+  THEN new host is selected
+  AND game state transfers correctly
+  AND gameplay resumes within 10 seconds
+
+SCENARIO: Reconnection
+  GIVEN Player 2 disconnects temporarily
+  WHEN Player 2 reconnects within 60 seconds
+  THEN Player 2 rejoins same session
+  AND state is synchronized
+  AND progress is preserved
+```
+
+## Network Simulation Tools
+
+### Unity
+
+```csharp
+// Using Unity Transport with Network Simulator
+using Unity.Netcode;
+
+public class NetworkSimulator : MonoBehaviour
+{
+    [SerializeField] private int latencyMs = 100;
+    [SerializeField] private float packetLossPercent = 5f;
+    [SerializeField] private int jitterMs = 20;
+
+    void Start()
+    {
+        var transport = NetworkManager.Singleton.GetComponent<UnityTransport>();
+        var simulator = transport.GetSimulatorParameters();
+
+        simulator.PacketDelayMS = latencyMs;
+        simulator.PacketDropRate = (int)(packetLossPercent * 100);
+        simulator.PacketJitterMS = jitterMs;
+    }
+}
+
+// Test
+[UnityTest]
+public IEnumerator Position_UnderLatency_ConvergesWithinThreshold()
+{
+    EnableNetworkSimulation(latencyMs: 200);
+
+    // Move player
+    player1.Move(Vector3.forward * 10);
+
+    yield return new WaitForSeconds(1f);
+
+    // Check other client's view
+    var player1OnClient2 = client2.GetPlayerPosition(player1.Id);
+    var actualPosition = player1.transform.position;
+
+    Assert.Less(Vector3.Distance(player1OnClient2, actualPosition), 0.5f);
+}
+```
+
+### Unreal
+
+```cpp
+// Using Network Emulation
+void UNetworkTestHelper::EnableLatencySimulation(int32 LatencyMs)
+{
+    if (UNetDriver* NetDriver = GetWorld()->GetNetDriver())
+    {
+        FPacketSimulationSettings Settings;
+        Settings.PktLag = LatencyMs;
+        Settings.PktLagVariance = LatencyMs / 10;
+        Settings.PktLoss = 0;
+
+        NetDriver->SetPacketSimulationSettings(Settings);
+    }
+}
+
+// Functional test for sync
+void AMultiplayerSyncTest::StartTest()
+{
+    Super::StartTest();
+
+    // Spawn item on server
+    APickupItem* Item = GetWorld()->SpawnActor<APickupItem>(
+        ItemClass, FVector(0, 0, 100));
+
+    // Wait for replication
+    FTimerHandle TimerHandle;
+    GetWorld()->GetTimerManager().SetTimer(TimerHandle, [this, Item]()
+    {
+        // Verify client has item
+        if (VerifyItemExistsOnAllClients(Item))
+        {
+            FinishTest(EFunctionalTestResult::Succeeded, "Item replicated");
+        }
+        else
+        {
+            FinishTest(EFunctionalTestResult::Failed, "Item not found on clients");
+        }
+    }, 2.0f, false);
+}
+```
+
+### Godot
+
+```gdscript
+# Network simulation
+extends Node
+
+var simulated_latency_ms := 0
+var packet_loss_percent := 0.0
+
+func _ready():
+    # Hook into network to simulate conditions
+    multiplayer.peer_packet_received.connect(_on_packet_received)
+
+func _on_packet_received(id: int, packet: PackedByteArray):
+    if packet_loss_percent > 0 and randf() < packet_loss_percent / 100:
+        return  # Drop packet
+
+    if simulated_latency_ms > 0:
+        await get_tree().create_timer(simulated_latency_ms / 1000.0).timeout
+
+    _process_packet(id, packet)
+
+# Test
+func test_position_sync_under_latency():
+    NetworkSimulator.simulated_latency_ms = 200
+
+    # Move player on host
+    host_player.position = Vector3(100, 0, 100)
+
+    await get_tree().create_timer(1.0).timeout
+
+    # Check client view
+    var client_view_position = client.get_remote_player_position(host_player.id)
+    var distance = host_player.position.distance_to(client_view_position)
+
+    assert_lt(distance, 1.0, "Position should converge within 1 unit")
+```
+
+## Dedicated Server Testing
+
+### Test Matrix
+
+| Scenario              | Test Focus                           |
+| --------------------- | ------------------------------------ |
+| Server startup        | Clean initialization, port binding   |
+| Client authentication | Login validation, session management |
+| Server tick rate      | Consistent updates under load        |
+| Maximum players       | Performance at player cap            |
+| Server crash recovery | State preservation, reconnection     |
+
+### Load Testing
+
+```
+SCENARIO: Maximum Players
+  GIVEN server configured for 64 players
+  WHEN 64 players connect
+  THEN all connections succeed
+  AND server tick rate stays above 60Hz
+  AND latency stays below 50ms
+
+SCENARIO: Stress Test
+  GIVEN 64 players performing actions simultaneously
+  WHEN running for 10 minutes
+  THEN no memory leaks
+  AND no desync events
+  AND server CPU below 80%
+```
+
+## Matchmaking Testing
+
+```
+SCENARIO: Skill-Based Matching
+  GIVEN players with skill ratings [1000, 1050, 2000, 2100]
+  WHEN matchmaking runs
+  THEN [1000, 1050] are grouped together
+  AND [2000, 2100] are grouped together
+
+SCENARIO: Region Matching
+  GIVEN players from US-East, US-West, EU
+  WHEN matchmaking runs
+  THEN players prefer same-region matches
+  AND cross-region only when necessary
+  AND latency is acceptable for all players
+
+SCENARIO: Queue Timeout
+  GIVEN player waiting in queue
+  WHEN 3 minutes pass without match
+  THEN matchmaking expands search criteria
+  AND player is notified of expanded search
+```
+
+## Security Testing
+
+| Vulnerability    | Test Method                 |
+| ---------------- | --------------------------- |
+| Speed hacking    | Validate movement on server |
+| Teleportation    | Check position delta limits |
+| Damage hacking   | Server-authoritative damage |
+| Packet injection | Validate packet checksums   |
+| Replay attacks   | Use unique session tokens   |
+
+## Performance Metrics
+
+| Metric                | Good      | Acceptable | Poor       |
+| --------------------- | --------- | ---------- | ---------- |
+| Round-trip latency    | < 50ms    | < 100ms    | > 150ms    |
+| Sync delta            | < 100ms   | < 200ms    | > 500ms    |
+| Packet loss tolerance | < 5%      | < 10%      | > 15%      |
+| Bandwidth per player  | < 10 KB/s | < 50 KB/s  | > 100 KB/s |
+| Server tick rate      | 60+ Hz    | 30+ Hz     | < 20 Hz    |
+
+## Best Practices
+
+### DO
+
+- Test with real network conditions, not just localhost
+- Simulate worst-case scenarios (high latency + packet loss)
+- Use server-authoritative design for competitive games
+- Implement lag compensation for fast-paced games
+- Test host migration paths
+- Log network events for debugging
+
+### DON'T
+
+- Trust client data for important game state
+- Assume stable connections
+- Skip testing with maximum player counts
+- Ignore edge cases (simultaneous actions)
+- Test only in ideal network conditions
+- Forget to test reconnection flows