Kitomas

SP V1 D2 I3

Dec 15th, 2025
224
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 9.28 KB | None | 0 0
  1. ---- Sound Profiles V1 Proposal (Draft 2) ----
  2.  
  3.  
  4.  
  5. 0. Introduction
  6.  
  7. Right now, our audio behavior is spread across scripts, scenes, and project
  8. settings. That makes it harder to change, easier to break unintentionally, and
  9. difficult to predict how one tweak will affect other gameplay states. It also
  10. forces designers to rely on programmers for even small adjustments, like trying
  11. a new mix, swapping a preset, or rewiring an audio asset, because those changes
  12. often require touching scene files or code.
  13.  
  14. Sound Profiles solve this by introducing a clear, centralized layer of
  15. abstraction for audio. Instead of editing scenes or code, the team can iterate
  16. on audio behavior safely in one, dedicated place, reducing risk to scene
  17. integrity and keeping changes consistent, controlled, and easy to maintain.
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25. 1. Overview
  26.  
  27. A Sound Profile is a self-contained JSON-based format describing how audio
  28. should behave within specific game contexts, without modifying scenes, scripts,
  29. or assets directly. The schema's main goal is to provide an abstraction layer
  30. for defining audio behavior separately from script behavior, while being
  31. accessible enough for non-technical team members to comfortably create and edit.
  32.  
  33. These profiles can be layered and swapped based on any kind of game state or
  34. condition, all with minimal coordination necessary between the technical and
  35. non-technical team members, hereon referred to as "programmers" and "designers"
  36. respectively.
  37.  
  38.  
  39.  
  40. 1.1 Pain Points Addressed / Why This System Exists
  41.  
  42. Without Sound Profiles:
  43. * Audio behavior is scattered between scripts, scenes, or project settings,
  44. which makes modification more difficult and unpredictable.
  45. * Changing settings relevant to one state often risks unintentionally
  46. affecting others.
  47. * Designers would need programmers to tweak even the simplest of audio logic
  48. or asset wiring, as trying new mixes, presets, etc. requires touching scene
  49. files or code directly.
  50.  
  51. With Sound Profiles:
  52. * Audio behavior is centralized to two file types (excluding whatever form
  53. sound categories and IDs take) that are external to any script or scene data.
  54. * Any designer or programmer can adjust audio behavior in isolation, making
  55. its definitions predictable and testable.
  56. * The extent to which coordination is necessary between designers and
  57. programmers is greatly reduced, and is mostly limited to agreeing on what
  58. profile(s) a given context(s) is relevant to and vice versa, as well as
  59. their name and use case.
  60. * Global accessibility mixes or effect chains become simple, if not one-line swaps.
  61. * Context-based mixing becomes trivial: transitions, menus, cutscenes, etc.
  62. * Future dynamic systems (ducking, RTPCs, property interpolation),
  63. get a stable backbone.
  64. * Schema allows for future, interactive authoring tools to be integrated.
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. 2. Sound Profiles
  73.  
  74. Modularity within a given profile is one of its main design principles.
  75. Each profile is effectively a container that requires a minimal amount of
  76. boilerplate, followed by any number of desired "property" objects. (!!! CITE;ELABORATE)
  77. These property objects define a wide range of settings and behaviors,
  78. from sound effect / sound category gain adjustments, to per-bus effect chains.
  79.  
  80. A single Sound Profile can do any number of things. However, limiting each one
  81. individually to serve 1-3 purposes is ideal in order to maximize modularity and
  82. reusability. For example, within a single profile, you could define an audio
  83. effect chain that can be used in multiple *Profile Contexts* (see sect. 2.2),
  84. where any change to that profile's settings would apply to any associated
  85. contexts, like a macro of sorts.
  86.  
  87.  
  88.  
  89. 2.1 Profile Definitions
  90.  
  91. At a high level, a profile contains the following *required* fields:
  92. * A schema version number (integer; 1 for V1)
  93. * A profile ID string
  94.  
  95. Followed by some combination of the following *optional* fields:
  96. * Comments, in the form of an array of strings.
  97. * 'overwrite' vs. 'append' boolean that determines how that profile applies
  98. its properties (ignored in V1; always set to overwrite). (!!! CITE;ELABORATE)
  99. * Any number of valid profile properties. Each property type will have its
  100. own dedicated mini-schema. (!!! CITE;ELABORATE)
  101.  
  102. All fields, required or not, are agnostic relative to their order in a profile,
  103. and can be placed in any desired order, as long as each are placed at the
  104. top-level of a profile. Profiles have a flat, top-level layout relative to the
  105. profile's root in order to further simplify its schema.
  106.  
  107. While V1 only supports overwrite for its load behavior, the structure should
  108. still accommodate 'append' (e.g., for additive/multiplicative gain or
  109. effect-chain extensions) load behavior to be added later with minimal
  110. redesigning of the schema.
  111.  
  112.  
  113.  
  114. 2.2 Profile Contexts
  115.  
  116. In order to separate audio pipeline behavior from anything implementation or
  117. game design-specific, profiles are instead attached to Profile *Contexts*.
  118. These are named identifiers that can represent *any* game state, such as:
  119. * Scene transitions
  120. * Menu screens
  121. * Map mode vs. NPC mode
  122. * Accessibility modes (e.g., "Soft Mix")
  123. * Any arbitrary state/tag/event the game defines later
  124.  
  125. This abstraction allows the underlying profile format to remain stable, even
  126. if the game's notion of "state" evolves or expands.
  127.  
  128. One Profile Context can theoretically contain multiple profiles to be applied
  129. all at once, and each profile can theoretically be attached to multiple contexts.
  130.  
  131. In future versions, it should be possible to bind certain parameters within
  132. a context to more specific, real-time states, like attenuating the game's volume
  133. globally whenever the game window goes out of focus, for example.
  134.  
  135.  
  136.  
  137. 2.3 Context Definitions
  138.  
  139. Profile Contexts are defined in a separate JSON file that contains a context
  140. ID, followed by an (optional) "priority" index (see sect. 2.4), followed by
  141. references to profile IDs in an array. Each profile's load order is determined
  142. by their placement in that array.
  143.  
  144. A context ID simply maps a name (e.g., "UI_MAINMENU", "CTX_CUTSCENE") to a
  145. profile (or profiles) that will be considered active while that context is live.
  146.  
  147.  
  148.  
  149. 2.4 Global Contexts
  150.  
  151. Some profiles must always be applied before or after any other context or only
  152. a select number of contexts, such as:
  153. * Accessibility mixes (e.g., Soft Mix vs. Normal Mix)
  154. * System-level music selection rules
  155. * Baseline gain adjustments
  156.  
  157. These profiles' load order is determined by the previously mentioned "priority"
  158. index, which is 0 by default. Values lower than a given priority will result in
  159. that context being applied *before* the other, whereas values higher than a given
  160. priority will result in it being applied *after* the other. For example,
  161. a priority of -1 will be applied before a priority of 0, which will too go before
  162. a priority of 1, and so on. If two contexts have the same priority value, the
  163. load behavior is determined by the order in which the context files are read.
  164.  
  165. With this system, implementing 'global' contexts is as simple as giving a
  166. context a very low or high index, while tying its state to something fairly
  167. static, like a value that is only set by the user adjusting an in-game setting.
  168.  
  169. This lets the team swap global mixes dynamically (e.g., toggling Low-Intensity
  170. mode) without altering any other Profile Context.
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178. 3. Structure Guidelines
  179.  
  180. (TBD)
  181. (field types are identified implicitly by its key name)
  182. (profile or profile context ids don't necessarily need to be all-caps)
  183.  
  184.  
  185.  
  186. 3.1 Profile Structure Example
  187.  
  188. {
  189. "version": 1,
  190. "profile_id": "SINGLE_LOWPASS",
  191. "append": false,
  192.  
  193. "comments": [
  194. "A special 'comments' field is desired, if not necessary,",
  195. "due to the fact that JSON itself does not have comments as a feature.",
  196. "However, formatting comments in this manner may also have a use case",
  197. "related to any future interactive authoring tools."
  198. ],
  199.  
  200. "effects_DSP": [
  201. <EFFECT SCHEMA TBD>
  202. ]
  203. }
  204.  
  205.  
  206.  
  207. 3.2 Profile Context Structure Example
  208.  
  209. {
  210. "version": 1,
  211. "context_id": "LPF_ENABLED",
  212. "priority": 2,
  213.  
  214. "comments": [
  215. "For consistency (among other things),",
  216. "contexts should have support for comments as well."
  217. ],
  218.  
  219. "profiles": [
  220. "SINGLE_LOWPASS"
  221. ]
  222. }
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230. ?. Footnotes / Implementation Notes
  231. (These will be assigned as actual footnotes in the final Google Doc!)
  232. * "RTPC" stands for "Real-Time Parameter Control"
  233. * Only one instance of each property type can exist per profile.
  234. An error is to be handled in the event of a malformed or duplicate property key.
  235. * The property key strings should be verbose enough to serve as the canonical
  236. specification name, with little to no elaboration (e.g., "effects").
  237. * Sound categories and IDs are TBD; schema in V1 spec should/will accommodate both.
  238. * Linear <-> dB conversion rules must be documented in specification.
  239. * Effect preset system is TBD and may be added as a 'V1.1' extension.
  240.  
  241.  
  242.  
  243. Personal Notes (not to be included in the final gdoc):
  244. should overwrite vs. append be placed inside the profile itself,
  245. or in each profile context, where the profile ID is the key, and the
  246. overwrite/append boolean is that key's value?
Advertisement
Add Comment
Please, Sign In to add comment