markcerqueira / soundcraft

Framework for Transducing a StarCraft 2 Game

SoundCraft - Framework for Transducing a StarCraft 2 Game¶ ↑

SOUNDCRAFT IN ACTION¶ ↑

Watch this quick demo video the SoundCraft framework in its first performance piece - GG Music!

RUNNING SOUNDCRAFT¶ ↑

1. Clone this repository onto your computer.

2. Run bundle install from the root of the directory to get the required gems.

3. Run ruby bank_parser.rb to start the bank parser/OSC dispatcher.

4. Run any programs that will receive OSC messages (the audio folder contains our sample audio implementation)

5. Play the custom maps from the Galaxy Editor or upload it to StarCraft 2 and play it from there!

FILES¶ ↑

• maps folder - Contains maps featuring the custom data-collecting triggers created for SoundCraft; play against an AI opponent when played from the Galaxy Editor or publish this map and play against others online

• bank_parser.rb - Ruby script that parses the XML bank files written by our custom map and dispatches OSC messages

• audio folder - our sample sonic mappings written in ChucK that receives OSC messages from the bank parser to produce sound

DATA FLOW¶ ↑

User data is collected as events occur (e.g. minerals collected, units die) or at fixed polling intervals (collecting APM, unit build progress) and written to XML bank files. Unfortunately, this is the only legitimate way to get data out of StarCraft 2, but the latency was found to be acceptable given we can control how often we poll for changes to these bank files. A Ruby script monitors the folder containing the bank files using guard/listen and when those files are modified, the XML files are parsed using Nokogiri and OSC messages are dispatched. Any OSC listener can catch those messages and process them to display data or produce sound.

If PRINT_DATA is defined in bank_parser.rb, data for each OSC message sent will be printed out. The print statements include the time in seconds since the program started running, OSC address, tags, and content sent. A blank line will be printed after an entire XML bank has been parsed. Debug print statements be disabled for live performances, but can be useful while developing. Here is some sample output for reference:

4.257: /lorkCraft/mineralBank.SC2Bank (si): total_minerals_collected, 160
4.257: /lorkCraft/mineralBank.SC2Bank (si): current_mineral_count, 240

5.412: /lorkCraft/unitsBuiltBank.SC2Bank (si): Nexus, 1
5.412: /lorkCraft/unitsBuiltBank.SC2Bank (si): Probe, 8

6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 1-Pylon, 22.2646
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 5-Gateway, 96.5087
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 6-Pylon, 47.5097
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 4-Gateway, 83.252
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 7-Gateway, 59.253
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 2-Pylon, 28.2714
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 0-Gateway, 15.7714
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 3-Pylon, 38.501
6.438: /lorkCraft/buildingProductionBank.SC2Bank (sf): 8-CyberneticsCore, 70.2636

6.438: /lorkCraft/buildingProductionBank.SC2Bank (si): Gateway, 4
6.438: /lorkCraft/buildingProductionBank.SC2Bank (si): Pylon, 4
6.438: /lorkCraft/buildingProductionBank.SC2Bank (si): CyberneticsCore, 1

7.928: /lorkCraft/scoreBank.SC2Bank (si): idle_production_time, 16
7.928: /lorkCraft/scoreBank.SC2Bank (si): vespene_collection_rate, 0
7.928: /lorkCraft/scoreBank.SC2Bank (si): enemy_structures_razed, 0
7.929: /lorkCraft/scoreBank.SC2Bank (si): mineral_collection_rate, 280
7.929: /lorkCraft/scoreBank.SC2Bank (si): resource_lost_all, 0
7.929: /lorkCraft/scoreBank.SC2Bank (si): total_resource_value_of_army, 0
7.930: /lorkCraft/scoreBank.SC2Bank (si): total_overview_score, 960
7.930: /lorkCraft/scoreBank.SC2Bank (si): workers_trained, 8
7.930: /lorkCraft/scoreBank.SC2Bank (si): enemy_units_killed, 0
7.930: /lorkCraft/scoreBank.SC2Bank (si): player_apm, 24
7.931: /lorkCraft/scoreBank.SC2Bank (si): average_minerals_stockpiled, 44
7.931: /lorkCraft/scoreBank.SC2Bank (si): workers_lost, 0

8.260: /lorkCraft/abilitiesUsedBank.SC2Bank (ss): Queen, SpawnLarva

8.947: /lorkCraft/buildingProductionBank.SC2Bank (sf): no__structure_production, 0.0

8.010: /lorkCraft/infoBank.SC2Bank (ss): player_race, Race/Name/Prot
8.010: /lorkCraft/infoBank.SC2Bank (ss): player_handle, marktronic
8.010: /lorkCraft/infoBank.SC2Bank (sf): elapsed_time, 60

9.236: /lorkCraft/unitProductionBank.SC2Bank (sf): 1-Zealot, 95.0195
9.236: /lorkCraft/unitProductionBank.SC2Bank (sf): 0-Probe, 72.0703
9.237: /lorkCraft/unitProductionBank.SC2Bank (sf): 2-Stalker, 95.752

9.419: /lorkCraft/cameraBank.SC2Bank (sf): cameraFocusX, 76.5
9.419: /lorkCraft/cameraBank.SC2Bank (sf): cameraFocusY, 9.7617

9.583: /lorkCraft/unitProductionBank.SC2Bank (sf): 0-Probe, 83.838

9.947: /lorkCraft/unitProductionBank.SC2Bank (sf): no__unit_production, 0.0

DATA COLLECTED BY THE CUSTOM TRIGGERS¶ ↑

• Write supply every time supply is used/made

• Write vespene collected/current count every time it changes

• Write mineral collected/current count every time it changes

• Write out messages a user types in chat

• Write out abilities used by units

• Write out current unit/building composition when a unit/building is built or dies

• Write out player handle, player race, current game time every 10 seconds

• Write out total upgrades researched when a player completes a research item

• Write out coordinates (x, y) of player’s current focus (i.e. where the player is currently focused on the map) every second

• Write out unit production status every second (a special no_unit_production message is sent when no units are being produced)

• Write out structure production status every second (a special no_structure_production message is sent when no structures are being built)

• Write general user info every second. This currently includes:

  • APM

  • Average Minerals Stockpiled

  • Average Vespene Stockpiled

  • Mineral Collection Rate

  • Vespene Collection Rate

  • Enemy Structures Razed

  • Enemy Units Killed

  • Mineral Value of Units Lost

  • Total Resource Value of Army

  • Workers Trained

  • Workers Lost

  • Total Overview Score

  • Supplies Used

  • ResourceLostAll

  • Idle Production Time

  • Combat Efficiency

  • Units Lost

  • Structures Lost

  • Weapons Upgrades Completed

  • Armor Upgrades Completed

LICENSE¶ ↑

SoundCraft is released under the MIT License.

COPYRIGHT NOTICES¶ ↑

Thanks Blizzard for making an awesome game and tools to build awesome things around that game - without their work, SoundCraft would not be a reality! Per Blizzard’s Copyright Notices FAQ here are a bunch of things we used and/or mentioned this project:

Battle.net®©1996 - 2011 Blizzard Entertainment, Inc. All rights reserved. Battle.net and Blizzard Entertainment are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.

Blizzard Entertainment®Blizzard Entertainment is a trademark or registered trademark of Blizzard Entertainment, Inc. in the U.S. and/or other countries. All rights reserved.

StarCraft®©1998 Blizzard Entertainment, Inc. All rights reserved. StarCraft and Blizzard Entertainment are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.

StarCraft® II: Wings of Liberty™©2010 Blizzard Entertainment, Inc. All rights reserved. Wings of Liberty is a trademark, and StarCraft and Blizzard Entertainment are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.