Chapter 9: Tooltime data parsing
The introduction explains why separating balance data from Unity scene and runtime assets can improve designers’ workflow, reduce runtime checks, and support live updates and testing.
After this chapter you will be able to
- External balance data workflow. Explain why moving balance data from the Game GameObject in the Unity scene to an external asset makes it easier for designers to edit, including when multiple designers want to make changes.
- Tool-time balance validation. Explain how validating separated balance data during tool time can reduce checks while the game runs.
- Live balance versions and tests. Describe why live balance updates need compatible, retained versions and how separate balance files can support an A/B test.
- Combined balance source of truth. Explain how the proposed approach uses both Google Sheets and ScriptableObjects, including which data the game ultimately relies on.
- Asset to runtime balance. Describe how the balance asset relates to runtime Balance and why separate assets can help as a game grows.
- Binary balance output. Describe how the BalanceParser writes balance data as binary and why it converts the byte stream to an array before saving it.
- Tool-time and runtime separation. Explain why balance-writing and balance-reading code are kept in separate files, and state where this example loads the balance from.
- Controlled balance loading sources. Justify limiting where balance is loaded from so the balance version a player is using remains identifiable. Explain how an unknown version obstructs reproducing a version-specific bug.
- Balance-dependent array allocation. Explain why arrays belonging to balance data would be allocated when the balance is loaded, and contrast that with the sizing of GameData arrays.
- Tool-time validation benefit. Explain how parsing balance at tool time permits validation before runtime use and why that can remove unnecessary runtime checks.
- Tool-time validation sequence. Describe when balance data is validated and what happens if validation fails.
- Runtime checks and code complexity. Explain why validating authored balance data ahead of time can simplify and speed up AllocateGameData(), and how the situation differs for untrusted data.
- Balance versions and app versions. Distinguish balance changes released with the app from live balance updates, and explain why the app version identifies the balance only in the first case.
- Live balance diagnostic records. Explain why investigating bugs or player departures after live updates requires knowing each affected user's balance version and retaining previous balances.
- Single-source balance loading. Describe the recommended loading source for release-only versus live-updated balance, and explain why mixing sources is discouraged.
- Retention comparison through A/B testing. Explain how splitting players between the old and new gold rewards helps assess whether the reward change improves retention, despite outside factors that also affect retention.
- Separate balances for test groups. Describe how keeping balance data separate from the game lets different groups receive different balance versions, and how that supports testing more than two variations.
- Collaborative balance development workflow. Describe how the project uses Google Sheets and ScriptableObjects to pass balance work among game designers, engineers, and QA.
- Tool-time balance validation. Explain why validating trusted balance data while parsing it into binary data can replace runtime checks.
- Balance version control and testing. Explain how separate balance files support live updates and A/B testing, while consistent version selection and retained old versions serve different purposes.
What it builds on
- The Balance (chapter 4) · Introduces balance data as the game's rules and tuning.
- Separating asset data from logic (chapter 8) · Provides the earlier example of separating editable asset data from assets.
- Saving to a local file (chapter 7) · The earlier GameData saving operation used as a comparison.
- AllocateGameData() - Allocating all the data for our game (chapter 4) · Allocating gameplay data according to balance settings.
Section by section
Introduction
The introduction explains why separating balance data from Unity scene and runtime assets can improve designers’ workflow, reduce runtime checks, and support live updates and testing.
- External balance data workflow: Explain why moving balance data from the Game GameObject in the Unity scene to an external asset makes it easier for designers to edit, including when multiple designers want to make changes.
Why it matters: The location of balance data affects how easily designers can tune the game. - Tool-time balance validation: Explain how validating separated balance data during tool time can reduce checks while the game runs.
Why it matters: Finding bad balance entries before runtime can simplify game code and avoid costly checks. - Live balance versions and tests: Describe why live balance updates need compatible, retained versions and how separate balance files can support an A/B test.
Why it matters: Balance changes can alter gameplay substantially, so teams need to deliver, investigate, and compare them reliably.
Key terms: balance data, Game GameObject, Unity scene, external asset, tool time, validating, parsing, runtime, live-updating the balance, versioning
9.1 Moving balance data to an external asset
The section explains why balance data moves out of the Game object, how Google Sheets and ScriptableObjects serve different needs, and how ScriptableObject data becomes the game's runtime balance.
- Google Sheets balance tradeoffs: Explain why Google Sheets is useful for developing balance data and why it is not the source of truth for the game.
Why it matters: This explains why a convenient design workspace still needs a controlled path into the game. - ScriptableObject balance tradeoffs: Distinguish the benefits and costs of storing balance in ScriptableObjects.
Why it matters: These tradeoffs explain why ScriptableObjects complement rather than simply replace designers' spreadsheets. - Combined balance source of truth: Explain how the proposed approach uses both Google Sheets and ScriptableObjects, including which data the game ultimately relies on.
Why it matters: The source-of-truth boundary makes clear which edits can actually affect a build. - New feature balance handoff: Trace the roles of designers, engineers, and QA when creating balance for a new feature.
Why it matters: The handoff lets engineers build against clear data requirements while designers and QA can still tune and test values. - Asset to runtime balance: Describe how the balance asset relates to runtime Balance and why separate assets can help as a game grows.
Why it matters: This separates assets that are convenient to edit from the balance representation the game loads.
Key terms: Google Sheets, balance, binary format, ScriptableObjects, version control, data types, source of truth, runtime balance file, game designer, engineer
9.2 Parsing the balance
This section explains how the BalanceParser produces a binary balance file at tool time and why balance versioning becomes more important if values can change after release.
- Binary balance output: Describe how the BalanceParser writes balance data as binary and why it converts the byte stream to an array before saving it.
Why it matters: The byte array makes the parsed balance available to save somewhere other than a local file. - Build-tied balance version: Explain why this tool-time balance file does not store its own version number.
Why it matters: It explains why a separate balance version number is unnecessary for the build-included file. - Live balance update limits: Distinguish changes to existing balance values from adding or removing balance data in a live update, and explain the versioning concern.
Why it matters: Live value changes can affect gameplay even when the structure of the balance cannot change.
Key terms: BalanceParser, FileStream, BinaryWriter, byte array, tool time, game version, balance, live-update, balance version, existing values
9.3 Loading the balance
This section explains why loading balance data differs from loading saved game data, including the need to control its source, allocate from its contents, and keep tool-time work out of runtime.
- Balance and game data distinction: Distinguish balance data, which defines game rules, from game data, which records the current state of play. Explain why the two call for different loading approaches.
Why it matters: The distinction explains why balance cannot simply be loaded like a game save. - Tool-time and runtime separation: Explain why balance-writing and balance-reading code are kept in separate files, and state where this example loads the balance from.
Why it matters: Separating the two phases keeps tool-only work and dependencies out of the shipped runtime. - Controlled balance loading sources: Justify limiting where balance is loaded from so the balance version a player is using remains identifiable. Explain how an unknown version obstructs reproducing a version-specific bug.
Why it matters: Knowing the player's balance version is essential when diagnosing gameplay that changes between releases. - Balance-dependent array allocation: Explain why arrays belonging to balance data would be allocated when the balance is loaded, and contrast that with the sizing of GameData arrays.
Why it matters: Allocation must wait until the data that determines an array's size is available. - Tool-time validation benefit: Explain how parsing balance at tool time permits validation before runtime use and why that can remove unnecessary runtime checks.
Why it matters: Moving validation out of runtime can reduce checks in gameplay code.
Key terms: balance data, game data, tool time, runtime, resource folder, balance version, multiple sources, LoadBalance(), GameData, Balance.NumEnemies
9.4 Validating balance data at tool time
This section explains how validating balance data before parsing lets the game avoid repeated runtime checks while catching authoring mistakes.
- Tool-time validation sequence: Describe when balance data is validated and what happens if validation fails.
Why it matters: Invalid balance settings are caught before they become data the game uses. - Runtime checks and code complexity: Explain why validating authored balance data ahead of time can simplify and speed up AllocateGameData(), and how the situation differs for untrusted data.
Why it matters: Moving checks out of gameplay code keeps a simple allocation function simple. - Practical validation targets: Describe the kinds of authoring mistakes validate() can catch and the section's suggested limit on adding checks.
Why it matters: Targeted validation catches likely content errors without turning the validator into a check of every field.
Key terms: validate(), parse(), tool time, balance.NumEnemies, AllocateGameData(), runtime checks, branches, MAX_ENEMIES, ScriptableObject, sprites
9.5 Handling live balance updates
This section explains why live balance updates require separate version tracking and recommends a single loading source to avoid uncertainty about which balance users have.
- Balance versions and app versions: Distinguish balance changes released with the app from live balance updates, and explain why the app version identifies the balance only in the first case.
Why it matters: Balance changes can substantially alter gameplay, so identifying what a user received matters. - Live balance diagnostic records: Explain why investigating bugs or player departures after live updates requires knowing each affected user's balance version and retaining previous balances.
Why it matters: Version records let a team relate reported bugs or users quitting to the balance those users experienced. - Single-source balance loading: Describe the recommended loading source for release-only versus live-updated balance, and explain why mixing sources is discouraged.
Why it matters: A consistent source reduces uncertainty about which balance a user loaded and where it came from.
Key terms: balance, app version, live-updating the balance, balance version, old balance versions, game data, single source, loaded locally, downloaded every time the user starts the game
9.6 A/B Testing
The section explains how separate balance data makes it easy to A/B test gameplay changes and compare their effect on player retention.
- Retention comparison through A/B testing: Explain how splitting players between the old and new gold rewards helps assess whether the reward change improves retention, despite outside factors that also affect retention.
Why it matters: Comparing groups is more informative than looking at retention after a change without accounting for other influences. - Separate balances for test groups: Describe how keeping balance data separate from the game lets different groups receive different balance versions, and how that supports testing more than two variations.
Why it matters: Separate balance versions let a team test gameplay changes without making a different game for each group.
Key terms: A/B testing, retention, balance, balance data, balance A, balance B
9.7 Conclusion
This conclusion explains how external balance data supports a collaborative workflow, tool-time validation, live updates, and controlled testing of balance versions.
- Collaborative balance development workflow: Describe how the project uses Google Sheets and ScriptableObjects to pass balance work among game designers, engineers, and QA.
Why it matters: Clarifying the data before implementation reduces back-and-forth caused by missing requirements. - Tool-time balance validation: Explain why validating trusted balance data while parsing it into binary data can replace runtime checks.
Why it matters: Moving these checks to tool time simplifies runtime code and avoids repeated work during play. - Balance version control and testing: Explain how separate balance files support live updates and A/B testing, while consistent version selection and retained old versions serve different purposes.
Why it matters: Knowing which balance a player used makes bugs reproducible and comparisons between balance changes meaningful.
Key terms: balance, Google Sheets, ScriptableObject, QA, tool time, binary data, runtime checks, live-updating the balance, single source, A/B testing
9.8 Summary
The chapter summary explains how to author, parse, validate, version, and test balance data kept separate from the game project.
Where this is used later
- Storing the new enemy data (chapter 10) · The earlier use of a ScriptableObject for balance data.
- Parsing the balance data (chapter 10) · Parses balance data as support for multiple enemies is added.
- Loading the balance data (chapter 10) · Loading expanded balance data depends on sizes determined by the loaded balance.
Concepts explained in this chapter
- validationThe process of checking data or references against validity constraints before use.
- balance dataThe example game's designer-authored gameplay settings, kept separate from runtime state.
- ScriptableObjectA Unity object type for storing data as reusable project assets independently of scene GameObjects and components.
- parsingAnalyzing encoded or structured input and converting it into program-readable values.
- A/B testA/B testing is an experiment that compares two or more variants by assigning them to different user groups and measuring the resulting outcomes.
- tool timeThe development or preparation phase in which game data is created, processed, or validated before runtime.
- live balance updateA live balance update is a change to gameplay-balance configuration delivered while players use the game without releasing a new game version.
- live asset updateChanging or replacing application content without requiring a new application build.
- backward compatibilityBackward compatibility is the ability of newer software or data formats to continue working with older versions or previously created data.
- data typeA specification of the kind of value a program element can represent and the operations and storage interpretation associated with it.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
