Add usage examples/docs for SB data.

Author: tec27

broodrep-wasm/README.md

@@ -31,7 +31,10 @@ fileInput.addEventListener('change', async event => {
     console.log('Replay parsed:', replay)
     console.log('Game title:', header.title)
     console.log('Map name:', header.mapName)
-    console.log('Players:', replay.players().filter(p => !p.isEmpty && !p.isObserver))
+    console.log(
+      'Players:',
+      replay.players().filter(p => !p.isEmpty && !p.isObserver),
+    )
   } catch (error) {
     console.error('Failed to parse replay:', error)
   }
@@ -78,16 +81,19 @@ Parses a StarCraft replay file and returns a Replay object for retrieving game i
 class Replay {
   readonly format: ReplayFormat // "legacy", "modern", or "modern121"
   readonly header: ReplayHeader // Game header information
-  
+
   // Methods for retrieving player information
   players(): Player[] // All player slots (including empty)
   observers(): Player[] // Only observers
   slots(): Player[] // All slots
   hostPlayer(): Player | undefined // The host player if identifiable
-  
+
   // Methods for retrieving raw section data
   getRawSection(section: ReplaySection): Uint8Array | undefined
   getRawCustomSection(section_id: number): Uint8Array | undefined
+
+  // Method for retrieving parsed ShieldBattery data
+  getShieldBatterySection(): ShieldBatteryData | undefined
 }
 
 interface ReplayHeader {
@@ -115,6 +121,29 @@ interface Player {
   isEmpty: boolean // Whether this is an empty slot
   isObserver: boolean // Whether this is an observer
 }
+
+interface ShieldBatteryData {
+  starcraftExeBuild: number // StarCraft executable build number
+  shieldbatteryVersion: string // ShieldBattery client version
+  teamGameMainPlayers: [number, number, number, number] // Main players in team games
+  startingRaces: [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+  ] // Starting race for each player
+  gameId: string // Game UUID on ShieldBattery
+  userIds: [number, number, number, number, number, number, number, number] // ShieldBattery user IDs
+  gameLogicVersion: number | undefined // Game logic version (if available)
+}
 ```
 
 ### `DecompressionConfig`
@@ -125,7 +154,7 @@ Configuration object for customizing security limits during replay parsing.
 // Create decompression config object
 const options = {
   maxDecompressedSize: 200 * 1024 * 1024, // 200MB
-  maxCompressionRatio: 1000.0 // Allow 1000:1 compression ratio
+  maxCompressionRatio: 1000.0, // Allow 1000:1 compression ratio
 }
 
 const replay = parseReplay(replayData, options)
@@ -143,6 +172,54 @@ configured due to limitations of Rust's time implementation.
 
 Returns the version of the broodrep library.
 
+## ShieldBattery Support
+
+The library includes support for parsing ShieldBattery-specific data from replays created through the [ShieldBattery](https://shieldbattery.net/) platform. This data provides additional context about games played on ShieldBattery.
+
+### Basic Usage
+
+```javascript
+import { parseReplay } from '@shieldbattery/broodrep'
+
+// Parse a replay
+const replay = parseReplay(replayData)
+
+// Check for ShieldBattery data
+const shieldBatteryData = replay.getShieldBatterySection()
+
+if (shieldBatteryData) {
+  console.log('Game ID:', shieldBatteryData.gameId)
+  console.log('StarCraft Build:', shieldBatteryData.starcraftExeBuild)
+  console.log('ShieldBattery Version:', shieldBatteryData.shieldbatteryVersion)
+
+  // Game logic version (if available in newer format)
+  if (shieldBatteryData.gameLogicVersion !== undefined) {
+    console.log('Game Logic Version:', shieldBatteryData.gameLogicVersion)
+  }
+
+  // User IDs of active players
+  const activeUserIds = shieldBatteryData.userIds.filter(id => id !== 0)
+  console.log('User IDs:', activeUserIds)
+
+  // Starting races as numbers (0=Zerg, 1=Terran, 2=Protoss, 6=Random)
+  const activePlayers = replay.players().filter(p => !p.isEmpty && !p.isObserver)
+  const startingRaces = shieldBatteryData.startingRaces.slice(0, activePlayers.length)
+  console.log('Starting Races:', startingRaces)
+} else {
+  console.log('No ShieldBattery data (normal for non-ShieldBattery replays)')
+}
+```
+
+### ShieldBatteryData Fields
+
+- **`gameId`**: Unique UUID for the game on ShieldBattery platform
+- **`starcraftExeBuild`**: Build number of the StarCraft executable used
+- **`shieldbatteryVersion`**: Version string of the ShieldBattery client
+- **`gameLogicVersion`**: Version of game logic modifications (if available)
+- **`userIds`**: Array of ShieldBattery user IDs corresponding to players
+- **`teamGameMainPlayers`**: Identifies main players in team games
+- **`startingRaces`**: Original race selection for each player slot (before randomization)
+
 ## Building
 
 ````bash

broodrep-wasm/examples/index.html

@@ -193,6 +193,7 @@ <h3>Players</h3>
                 <th>Team</th>
                 <th>Type</th>
                 <th>Slot</th>
+                <th>Network ID</th>
               </tr>
             </thead>
             <tbody id="playersTableBody"></tbody>
@@ -212,6 +213,11 @@ <h3>Observers</h3>
             <tbody id="observersTableBody"></tbody>
           </table>
         </div>
+
+        <div class="info-section" id="shieldBatterySection" style="display: none">
+          <h3>ShieldBattery Data</h3>
+          <div class="info-grid" id="shieldBatteryInfo"></div>
+        </div>
       </div>
     </div>
 
@@ -327,6 +333,7 @@ <h3>Observers</h3>
                     <td>${player.team}</td>
                     <td>${player.playerType}</td>
                     <td>${player.slotId}</td>
+                    <td>${player.networkId}</td>
                 </tr>
             `,
           )
@@ -353,6 +360,82 @@ <h3>Observers</h3>
           observersSection.style.display = 'none'
         }
 
+        // ShieldBattery Data
+        const shieldBatterySection = document.getElementById('shieldBatterySection')
+        const shieldBatteryInfo = document.getElementById('shieldBatteryInfo')
+
+        const shieldBatteryData = replay.getShieldBatterySection()
+        if (shieldBatteryData) {
+          shieldBatterySection.style.display = 'block'
+
+          const raceNames = ['Zerg', 'Terran', 'Protoss']
+          const startingRaces = shieldBatteryData.startingRaces
+            .map(race => raceNames[race] || `Random`)
+            .join(', ')
+
+          const activeUserIds = shieldBatteryData.userIds.filter(id => id !== 0)
+          const mainPlayers = shieldBatteryData.teamGameMainPlayers
+
+          shieldBatteryInfo.innerHTML = `
+            <div class="info-item">
+              <div class="info-label">Game ID</div>
+              <div class="info-value" style="font-family: monospace; font-size: 0.9em;">${
+                shieldBatteryData.gameId
+              }</div>
+            </div>
+            <div class="info-item">
+              <div class="info-label">StarCraft Build</div>
+              <div class="info-value">${shieldBatteryData.starcraftExeBuild}</div>
+            </div>
+            <div class="info-item">
+              <div class="info-label">ShieldBattery Version</div>
+              <div class="info-value">${shieldBatteryData.shieldbatteryVersion}</div>
+            </div>
+            ${
+              shieldBatteryData.gameLogicVersion !== undefined
+                ? `
+            <div class="info-item">
+              <div class="info-label">Game Logic Version</div>
+              <div class="info-value">${shieldBatteryData.gameLogicVersion}</div>
+            </div>
+            `
+                : ''
+            }
+            ${
+              startingRaces
+                ? `
+            <div class="info-item">
+              <div class="info-label">Starting Races</div>
+              <div class="info-value">${startingRaces}</div>
+            </div>
+            `
+                : ''
+            }
+            ${
+              activeUserIds.length > 0
+                ? `
+            <div class="info-item">
+              <div class="info-label">User IDs</div>
+              <div class="info-value">[${activeUserIds.join(', ')}]</div>
+            </div>
+            `
+                : ''
+            }
+            ${
+              mainPlayers.length > 0
+                ? `
+            <div class="info-item">
+              <div class="info-label">Team Game Main Players</div>
+              <div class="info-value">[${mainPlayers.join(', ')}]</div>
+            </div>
+            `
+                : ''
+            }
+          `
+        } else {
+          shieldBatterySection.style.display = 'none'
+        }
+
         replayInfo.style.display = 'block'
       }
 

broodrep-wasm/examples/usage.mjs

@@ -210,13 +210,108 @@ function customOptionsExample() {
   }
 }
 
+/**
+ * Example 5: ShieldBattery data extraction
+ */
+function shieldBatteryExample() {
+  console.log('\n=== ShieldBattery Data Example ===')
+
+  // Try to find a ShieldBattery replay
+  const sbReplayPath = path.join(
+    import.meta.dirname,
+    '..',
+    '..',
+    'broodrep',
+    'testdata',
+    'sb_data.rep',
+  )
+
+  let testReplayPath = sbReplayPath
+  if (!fs.existsSync(sbReplayPath)) {
+    // Fall back to a regular replay for demonstration
+    testReplayPath = path.join(
+      import.meta.dirname,
+      '..',
+      '..',
+      'broodrep',
+      'testdata',
+      'things.rep',
+    )
+    console.log('No ShieldBattery replay found, using regular replay for demonstration...')
+  }
+
+  if (!fs.existsSync(testReplayPath)) {
+    console.log('No test replay found, skipping ShieldBattery example...')
+    return
+  }
+
+  try {
+    const replayData = fs.readFileSync(testReplayPath)
+    const uint8Array = new Uint8Array(replayData)
+    const replay = parseReplay(uint8Array)
+
+    // Try to get ShieldBattery data
+    const shieldBatteryData = replay.getShieldBatterySection()
+
+    if (shieldBatteryData) {
+      console.log('✓ Found ShieldBattery data!')
+      console.log('ShieldBattery Information:')
+      console.log(`  Game ID: ${shieldBatteryData.gameId}`)
+      console.log(`  StarCraft Build: ${shieldBatteryData.starcraftExeBuild}`)
+      console.log(`  ShieldBattery Version: ${shieldBatteryData.shieldbatteryVersion}`)
+
+      if (shieldBatteryData.gameLogicVersion !== undefined) {
+        console.log(`  Game Logic Version: ${shieldBatteryData.gameLogicVersion}`)
+      }
+
+      // Show team game main players (if applicable)
+      const mainPlayers = shieldBatteryData.teamGameMainPlayers
+      console.log(`  Team Game Main Players: [${mainPlayers.join(', ')}]`)
+
+      // Show user IDs
+      const activeUserIds = shieldBatteryData.userIds.filter(id => id !== 0)
+      if (activeUserIds.length > 0) {
+        console.log(`  User IDs: [${activeUserIds.join(', ')}]`)
+      }
+
+      // Show starting races (as race names)
+      const raceNames = ['Zerg', 'Terran', 'Protoss']
+      const startingRaces = shieldBatteryData.startingRaces.map(race => raceNames[race] || 'Random')
+
+      if (startingRaces.length > 0) {
+        console.log(`  Starting Races: [${startingRaces.join(', ')}]`)
+      }
+    } else {
+      console.log('ℹ No ShieldBattery data found in this replay')
+      console.log('  This is normal for replays not created through ShieldBattery')
+    }
+
+    // Also demonstrate raw section access
+    console.log('\nRaw Section Access:')
+    const headerSection = replay.getRawSection('header')
+    if (headerSection) {
+      console.log(`  Header section: ${headerSection.length} bytes`)
+    }
+
+    const shieldBatterySection = replay.getRawSection('shieldBattery')
+    if (shieldBatterySection) {
+      console.log(`  ShieldBattery section: ${shieldBatterySection.length} bytes (raw)`)
+    } else {
+      console.log(`  No ShieldBattery section found`)
+    }
+  } catch (error) {
+    console.error('✗ ShieldBattery example failed:', error)
+  }
+}
+
 console.log('broodrep-wasm Usage Examples')
 console.log('============================')
 
 basicExample()
 detailedExample()
 errorHandlingExample()
 customOptionsExample()
+shieldBatteryExample()
 
 console.log('\n✓ All examples completed!')
 console.log('\nTip: To use in your project:')