@carbonenginejs/runtime-resource 0.12.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (238) hide show
  1. package/README.md +21 -0
  2. package/dist/CjsResMan.js +393 -29
  3. package/dist/CjsResMan.js.map +1 -1
  4. package/dist/format/carbonEffect/CjsCarbonEffectReader.js +165 -118
  5. package/dist/format/carbonEffect/CjsCarbonEffectReader.js.map +1 -1
  6. package/dist/format/carbonEffect/buildCarbonEffectContainer.js +182 -0
  7. package/dist/format/carbonEffect/buildCarbonEffectContainer.js.map +1 -0
  8. package/dist/format/carbonEffect/carbonEffectBackendBlock.js +7 -113
  9. package/dist/format/carbonEffect/carbonEffectBackendBlock.js.map +1 -1
  10. package/dist/format/carbonEffect/carbonEffectRecords.js +258 -66
  11. package/dist/format/carbonEffect/carbonEffectRecords.js.map +1 -1
  12. package/dist/format/carbonEffect/carbonEffectResourceTransform.js +197 -0
  13. package/dist/format/carbonEffect/carbonEffectResourceTransform.js.map +1 -0
  14. package/dist/format/effect/effectBodyInventory.js +146 -0
  15. package/dist/format/effect/effectBodyInventory.js.map +1 -0
  16. package/dist/format/effect/effectPermutationGraph.js +13 -13
  17. package/dist/format/effect/effectPermutationGraph.js.map +1 -1
  18. package/dist/format/index.js +4 -4
  19. package/dist/formats/black/CjsBlackFormat.js +19 -1
  20. package/dist/formats/black/CjsBlackFormat.js.map +1 -1
  21. package/dist/formats/bnk/CjsBnkFormat.js +28 -9
  22. package/dist/formats/bnk/CjsBnkFormat.js.map +1 -1
  23. package/dist/formats/bnk/core/busNodes.js +252 -0
  24. package/dist/formats/bnk/core/busNodes.js.map +1 -0
  25. package/dist/formats/bnk/core/effectNodes.js +147 -0
  26. package/dist/formats/bnk/core/effectNodes.js.map +1 -0
  27. package/dist/formats/bnk/core/eventAction.js +135 -24
  28. package/dist/formats/bnk/core/eventAction.js.map +1 -1
  29. package/dist/formats/bnk/core/globalSettings.js +215 -0
  30. package/dist/formats/bnk/core/globalSettings.js.map +1 -0
  31. package/dist/formats/bnk/core/helpers.js +37 -5
  32. package/dist/formats/bnk/core/helpers.js.map +1 -1
  33. package/dist/formats/bnk/core/musicNodes.js +43 -19
  34. package/dist/formats/bnk/core/musicNodes.js.map +1 -1
  35. package/dist/formats/bnk/core/nodeBase.js +28 -7
  36. package/dist/formats/bnk/core/nodeBase.js.map +1 -1
  37. package/dist/formats/dds/core/helpers.js +40 -1
  38. package/dist/formats/dds/core/helpers.js.map +1 -1
  39. package/dist/formats/dxbc/CjsDxbcFormat.js +45 -0
  40. package/dist/formats/dxbc/CjsDxbcFormat.js.map +1 -1
  41. package/dist/formats/dxbc/core/disassemble.js +240 -0
  42. package/dist/formats/dxbc/core/disassemble.js.map +1 -0
  43. package/dist/formats/gltf/CjsGltfFormat.js +1 -39
  44. package/dist/formats/gltf/CjsGltfFormat.js.map +1 -1
  45. package/dist/formats/gltf/core/helpers.js +1 -21
  46. package/dist/formats/gltf/core/helpers.js.map +1 -1
  47. package/dist/formats/hlsl/CjsHlslFormat.js +0 -21
  48. package/dist/formats/hlsl/CjsHlslFormat.js.map +1 -1
  49. package/dist/formats/hlsl/core/carbonDescriptionToRuntime.js +118 -49
  50. package/dist/formats/hlsl/core/carbonDescriptionToRuntime.js.map +1 -1
  51. package/dist/formats/hlsl/core/detailMapFamily.js +128 -0
  52. package/dist/formats/hlsl/core/detailMapFamily.js.map +1 -0
  53. package/dist/formats/hlsl/core/localLightFamily.js +133 -0
  54. package/dist/formats/hlsl/core/localLightFamily.js.map +1 -0
  55. package/dist/formats/hlsl/core/tr2/resources/HlslEffectRes.js +79 -73
  56. package/dist/formats/hlsl/core/tr2/resources/HlslEffectRes.js.map +1 -1
  57. package/dist/formats/hlsl/core/tr2/shader/HlslEffectBindingManifest.js +8 -1
  58. package/dist/formats/hlsl/core/tr2/shader/HlslEffectBindingManifest.js.map +1 -1
  59. package/dist/formats/hlsl/core/tr2/shader/HlslEffectDescription.js +11 -691
  60. package/dist/formats/hlsl/core/tr2/shader/HlslEffectDescription.js.map +1 -1
  61. package/dist/formats/index.js +4 -2
  62. package/dist/formats/index.js.map +1 -1
  63. package/dist/formats/obj/CjsObjFormat.js +1 -22
  64. package/dist/formats/obj/CjsObjFormat.js.map +1 -1
  65. package/dist/formats/obj/core/helpers.js +1 -21
  66. package/dist/formats/obj/core/helpers.js.map +1 -1
  67. package/dist/formats/pickle/CjsPickleFormat.js +214 -0
  68. package/dist/formats/pickle/CjsPickleFormat.js.map +1 -0
  69. package/dist/formats/pickle/core/CjsPickleProtocol0Reader.js +551 -0
  70. package/dist/formats/pickle/core/CjsPickleProtocol0Reader.js.map +1 -0
  71. package/dist/formats/pickle/index.js +2 -0
  72. package/dist/formats/pickle/index.js.map +1 -0
  73. package/dist/formats/red/core/redGraph.js +11 -8
  74. package/dist/formats/red/core/redGraph.js.map +1 -1
  75. package/dist/formats/stl/CjsStlFormat.js +1 -46
  76. package/dist/formats/stl/CjsStlFormat.js.map +1 -1
  77. package/dist/formats/stl/core/helpers.js +1 -21
  78. package/dist/formats/stl/core/helpers.js.map +1 -1
  79. package/dist/formats/webgl/CjsWebglFormat.js +33 -55
  80. package/dist/formats/webgl/CjsWebglFormat.js.map +1 -1
  81. package/dist/formats/webgl/core/buildGlslEffectContainer.js +70 -0
  82. package/dist/formats/webgl/core/buildGlslEffectContainer.js.map +1 -0
  83. package/dist/formats/webgl/core/effectPackage.js +216 -108
  84. package/dist/formats/webgl/core/effectPackage.js.map +1 -1
  85. package/dist/formats/webgl/core/errors.js +1 -1
  86. package/dist/formats/webgl/core/errors.js.map +1 -1
  87. package/dist/formats/webgl/core/glsl/DxbcGlslEmitter.js +166 -24
  88. package/dist/formats/webgl/core/glsl/DxbcGlslEmitter.js.map +1 -1
  89. package/dist/formats/webgl/core/glsl/DxbcGlslOperandFormatter.js +63 -5
  90. package/dist/formats/webgl/core/glsl/DxbcGlslOperandFormatter.js.map +1 -1
  91. package/dist/formats/webgl/core/glsl/packedLightFixups.js +98 -0
  92. package/dist/formats/webgl/core/glsl/packedLightFixups.js.map +1 -0
  93. package/dist/formats/webgl/core/glslBackendBlock.js +552 -0
  94. package/dist/formats/webgl/core/glslBackendBlock.js.map +1 -0
  95. package/dist/formats/webgl/core/glslBackendBodySet.js +243 -0
  96. package/dist/formats/webgl/core/glslBackendBodySet.js.map +1 -0
  97. package/dist/formats/webgl/core/{cewgCompleteness.js → glslEffectCompleteness.js} +12 -8
  98. package/dist/formats/webgl/core/glslEffectCompleteness.js.map +1 -0
  99. package/dist/formats/webgl/core/helpers.js +33 -172
  100. package/dist/formats/webgl/core/helpers.js.map +1 -1
  101. package/dist/formats/webgl/core/inspectGlslEffectContainer.js +122 -0
  102. package/dist/formats/webgl/core/inspectGlslEffectContainer.js.map +1 -0
  103. package/dist/formats/webgl/core/readGlslEffectContainer.js +249 -0
  104. package/dist/formats/webgl/core/readGlslEffectContainer.js.map +1 -0
  105. package/dist/formats/webgpu/CjsWebgpuFormat.js +15 -15
  106. package/dist/formats/webgpu/CjsWebgpuFormat.js.map +1 -1
  107. package/dist/formats/webgpu/core/buildCarbonEffectContainer.js +37 -145
  108. package/dist/formats/webgpu/core/buildCarbonEffectContainer.js.map +1 -1
  109. package/dist/formats/webgpu/core/{cewgpu/CewgpuContainer.js → carbonWebgpu/CarbonWebgpuContainer.js} +13 -27
  110. package/dist/formats/webgpu/core/carbonWebgpu/CarbonWebgpuContainer.js.map +1 -0
  111. package/dist/formats/webgpu/core/{cewgpu → carbonWebgpu}/containerViews.js +1 -1
  112. package/dist/formats/webgpu/core/carbonWebgpu/containerViews.js.map +1 -0
  113. package/dist/formats/webgpu/core/{cewgpu → carbonWebgpu}/validateContainer.js +4 -4
  114. package/dist/formats/webgpu/core/carbonWebgpu/validateContainer.js.map +1 -0
  115. package/dist/formats/webgpu/core/effectBackendBodySet.js +18 -18
  116. package/dist/formats/webgpu/core/effectBackendBodySet.js.map +1 -1
  117. package/dist/formats/webgpu/core/errors.js +1 -1
  118. package/dist/formats/webgpu/core/errors.js.map +1 -1
  119. package/dist/formats/webgpu/core/helpers.js +22 -22
  120. package/dist/formats/webgpu/core/helpers.js.map +1 -1
  121. package/dist/formats/webgpu/core/packageEffect.js +11 -15
  122. package/dist/formats/webgpu/core/packageEffect.js.map +1 -1
  123. package/dist/formats/webgpu/core/packageEffectSelection.js +1 -1
  124. package/dist/formats/webgpu/core/packageEffectSelection.js.map +1 -1
  125. package/dist/formats/webgpu/core/wgsl/buildResourceTransformPlan.js +23 -23
  126. package/dist/formats/webgpu/core/wgsl/buildResourceTransformPlan.js.map +1 -1
  127. package/dist/formats/webgpu/core/wgsl/buildWgslSet.js +6 -6
  128. package/dist/formats/webgpu/core/wgsl/buildWgslSet.js.map +1 -1
  129. package/dist/formats/yaml/CjsYamlFormat.js +3 -3
  130. package/dist/formats/yaml/CjsYamlFormat.js.map +1 -1
  131. package/dist/formats/yaml/core/CjsYamlReader.js +4 -6
  132. package/dist/formats/yaml/core/CjsYamlReader.js.map +1 -1
  133. package/dist/formats/yaml/core/helpers.js +27 -1
  134. package/dist/formats/yaml/core/helpers.js.map +1 -1
  135. package/dist/index.js +2 -0
  136. package/dist/index.js.map +1 -1
  137. package/dist/resource/CjsLoadingObject.js +19 -0
  138. package/dist/resource/CjsLoadingObject.js.map +1 -0
  139. package/dist/resource/CjsResource.js +4 -0
  140. package/dist/resource/CjsResource.js.map +1 -1
  141. package/dist/resource/ResourceHandlerMode.js +14 -0
  142. package/dist/resource/ResourceHandlerMode.js.map +1 -0
  143. package/dist/resource/index.js +2 -0
  144. package/dist/resource/index.js.map +1 -1
  145. package/dist/resource/shader/Tr2EffectRes.js +118 -213
  146. package/dist/resource/shader/Tr2EffectRes.js.map +1 -1
  147. package/dist/resource/shader/Tr2Shader.js +37 -15
  148. package/dist/resource/shader/Tr2Shader.js.map +1 -1
  149. package/dist/resource/shader/reflection/Tr2EffectConstant.js +37 -29
  150. package/dist/resource/shader/reflection/Tr2EffectConstant.js.map +1 -1
  151. package/dist/resource/shader/reflection/Tr2EffectDescription.js +39 -34
  152. package/dist/resource/shader/reflection/Tr2EffectDescription.js.map +1 -1
  153. package/dist/resource/shader/reflection/Tr2EffectLibrary.js +51 -30
  154. package/dist/resource/shader/reflection/Tr2EffectLibrary.js.map +1 -1
  155. package/dist/resource/shader/reflection/Tr2EffectParameterAnnotation.js +45 -25
  156. package/dist/resource/shader/reflection/Tr2EffectParameterAnnotation.js.map +1 -1
  157. package/dist/resource/shader/reflection/Tr2EffectResource.js +51 -17
  158. package/dist/resource/shader/reflection/Tr2EffectResource.js.map +1 -1
  159. package/dist/resource/shader/reflection/Tr2EffectStageInput.js +219 -88
  160. package/dist/resource/shader/reflection/Tr2EffectStageInput.js.map +1 -1
  161. package/dist/resource/shader/reflection/Tr2EffectTechnique.js +28 -18
  162. package/dist/resource/shader/reflection/Tr2EffectTechnique.js.map +1 -1
  163. package/dist/resource/shader/reflection/Tr2Pass.js +96 -39
  164. package/dist/resource/shader/reflection/Tr2Pass.js.map +1 -1
  165. package/dist/resource/shader/reflection/carbonRecordFields.js +159 -0
  166. package/dist/resource/shader/reflection/carbonRecordFields.js.map +1 -0
  167. package/dist/resource/shader/reflection/shaderStage.js +22 -0
  168. package/dist/resource/shader/reflection/shaderStage.js.map +1 -0
  169. package/dist/resource/shader/sampler/Tr2SamplerSetup.js +68 -10
  170. package/dist/resource/shader/sampler/Tr2SamplerSetup.js.map +1 -1
  171. package/dist/worker/CjsResManMainThreadLoader.js +9 -7
  172. package/dist/worker/CjsResManMainThreadLoader.js.map +1 -1
  173. package/dist/worker/CjsResManWorker.js +5 -4
  174. package/dist/worker/CjsResManWorker.js.map +1 -1
  175. package/dist/worker/CjsResManWorkerLoader.js +9 -6
  176. package/dist/worker/CjsResManWorkerLoader.js.map +1 -1
  177. package/docs/README.md +2 -2
  178. package/docs/architecture.md +12 -3
  179. package/docs/concepts/resource-lifecycle.md +9 -8
  180. package/docs/concepts/shader-resource-model.md +14 -17
  181. package/docs/concepts/writing-an-engine-adapter.md +1 -1
  182. package/docs/formats/README.md +4 -2
  183. package/docs/formats/carbon-effect-container.md +127 -26
  184. package/docs/formats/dxbc/architecture.md +1 -1
  185. package/docs/formats/dxbc/reference/api.md +28 -0
  186. package/docs/formats/hlsl/README.md +3 -3
  187. package/docs/formats/hlsl/architecture.md +8 -9
  188. package/docs/formats/hlsl/guides/hydrating-json-output.md +3 -5
  189. package/docs/formats/hlsl/guides/reading-effects.md +5 -1
  190. package/docs/formats/hlsl/reference/advanced-analysis.md +20 -25
  191. package/docs/formats/hlsl/reference/api.md +0 -7
  192. package/docs/formats/hlsl/reference/json-graph.md +1 -4
  193. package/docs/formats/pickle.md +82 -0
  194. package/docs/formats/webgl/README.md +71 -13
  195. package/docs/formats/webgl/architecture.md +16 -17
  196. package/docs/formats/webgl/carbon-constant-layouts.md +3 -3
  197. package/docs/formats/webgl/decl-io.md +3 -3
  198. package/docs/formats/webgl/memory-structured.md +27 -8
  199. package/docs/formats/webgl/texture-sample.md +1 -1
  200. package/docs/formats/webgpu/README.md +3 -3
  201. package/docs/formats/webgpu/architecture.md +5 -6
  202. package/docs/formats/webgpu/formats/{cewgpu.md → carbon-webgpu.md} +10 -11
  203. package/docs/formats/webgpu/guides/effect-packaging.md +6 -8
  204. package/docs/formats/webgpu/reference/api.md +11 -12
  205. package/docs/formats/webgpu/reference/wgsl-compatibility.md +11 -8
  206. package/docs/formats/wwise.md +63 -2
  207. package/docs/reference/classes/core.md +10 -0
  208. package/docs/reference/classes/formats.md +40 -48
  209. package/docs/reference/classes/resources.md +2 -2
  210. package/docs/reference/queues.md +88 -4
  211. package/docs/reference/workers.md +7 -0
  212. package/package.json +61 -61
  213. package/dist/format/carbonEffect/carbonDescriptionFromPortable.js +0 -372
  214. package/dist/format/carbonEffect/carbonDescriptionFromPortable.js.map +0 -1
  215. package/dist/format/effect/effectReflectionPackage.js +0 -636
  216. package/dist/format/effect/effectReflectionPackage.js.map +0 -1
  217. package/dist/formats/hlsl/core/HlslReader.js +0 -16
  218. package/dist/formats/hlsl/core/HlslReader.js.map +0 -1
  219. package/dist/formats/hlsl/core/portableReflection.js +0 -848
  220. package/dist/formats/hlsl/core/portableReflection.js.map +0 -1
  221. package/dist/formats/hlsl/portable.js +0 -2
  222. package/dist/formats/hlsl/portable.js.map +0 -1
  223. package/dist/formats/webgl/core/cewg/CewgPackage.js +0 -340
  224. package/dist/formats/webgl/core/cewg/CewgPackage.js.map +0 -1
  225. package/dist/formats/webgl/core/cewg/CewgPackageBuilder.js +0 -104
  226. package/dist/formats/webgl/core/cewg/CewgPackageBuilder.js.map +0 -1
  227. package/dist/formats/webgl/core/cewg/binary.js +0 -19
  228. package/dist/formats/webgl/core/cewg/binary.js.map +0 -1
  229. package/dist/formats/webgl/core/cewgCompleteness.js.map +0 -1
  230. package/dist/formats/webgl/core/effectPackageValidation.js +0 -331
  231. package/dist/formats/webgl/core/effectPackageValidation.js.map +0 -1
  232. package/dist/formats/webgpu/core/cewgpu/CewgpuContainer.js.map +0 -1
  233. package/dist/formats/webgpu/core/cewgpu/containerViews.js.map +0 -1
  234. package/dist/formats/webgpu/core/cewgpu/validateContainer.js.map +0 -1
  235. package/dist/resource/shader/portable.js +0 -33
  236. package/dist/resource/shader/portable.js.map +0 -1
  237. package/docs/formats/hlsl/reference/portable-reflection.md +0 -141
  238. package/docs/formats/webgl/effect-reflection.md +0 -127
@@ -20,9 +20,18 @@ lists, action type/target, sound and music-track source ids). For bank
20
20
  generator version 150, recognized Event Actions additionally expose exact
21
21
  scope/mode, property and range bundles, delay/transition/probability values,
22
22
  fade and action flags, exceptions, and Play bank identities. The
23
- Wwise-domain toolkit is grouped under the `CjsBnkFormat.wwise` static: the
23
+ recognized action-specific tails include Voice Volume/Pitch, Bus Volume, and
24
+ Voice low-pass/high-pass values,
25
+ Set State/Switch group/value identities, and Set/Reset Game Parameter values,
26
+ scopes, absolute/relative meaning, default, randomized delay/transition,
27
+ curve, transition-bypass flag, and exceptions. Voice property actions retain
28
+ the real variable-length exception records after their value bundle; timing
29
+ randomizers in the common property bundle are accepted independently of the
30
+ action-specific value randomizer. These fields are preserved by the reader
31
+ even when the currently inspected EVE corpus uses only a subset.
32
+ The Wwise-domain toolkit is grouped under the `CjsBnkFormat.wwise` static: the
24
33
  SoundbanksInfo catalog helpers, the FNV-1 id hash, event-to-media resolution,
25
- typed Event Actions, and typed authored-SFX nodes:
34
+ typed Global Settings and Event Actions, and typed authored-SFX nodes:
26
35
 
27
36
  ```js
28
37
  import { CjsBnkFormat } from "@carbonenginejs/runtime-resource/formats/bnk";
@@ -32,6 +41,9 @@ const inspections = bankByteArrays.map(bytes => CjsBnkFormat.inspect(bytes));
32
41
  const action = CjsBnkFormat.wwise.parseEventAction(actionPayload, {
33
42
  bankVersion: 150
34
43
  });
44
+ const globalSettings = CjsBnkFormat.wwise.parseGlobalSettings(stmgPayload, {
45
+ bankVersion: 150
46
+ });
35
47
  const { eventMedia } = CjsBnkFormat.wwise.eventMediaFromBanks(inspections);
36
48
  // eventMedia: Map<eventObjectId, Set<wemId>> - banks may split events from
37
49
  // their target sounds, so pass every related bank to one call.
@@ -46,6 +58,20 @@ const {
46
58
  diagnostics
47
59
  } = CjsBnkFormat.wwise.sfxNodesFromBanks(inspections);
48
60
 
61
+ const { nodes: musicNodes } =
62
+ CjsBnkFormat.wwise.musicNodesFromBanks(inspections);
63
+ // Every v150 music node retains its common NodeBase routing and property
64
+ // data. Track lookAheadTime is the authored signed millisecond value.
65
+
66
+ const { buses } = CjsBnkFormat.wwise.busNodesFromBanks(inspections);
67
+ // buses: Map<busId, { type, overrideBusId, outputDeviceId, properties,
68
+ // busVolume, makeUpGain, outputBusVolume, aux, ducks,
69
+ // fx, metadata, rtpcs, state }>
70
+
71
+ const { effects } = CjsBnkFormat.wwise.effectNodesFromBanks(inspections);
72
+ // effects: Map<effectId, { type, pluginId, parameterBlock, media,
73
+ // rtpcs, state, propertyValues }>
74
+
49
75
  const ogg = CjsWemFormat.toOgg(wemBytes); // Wwise Vorbis -> Ogg (lossless)
50
76
  const pcm = CjsWemFormat.toPcm(wemBytes); // PTADPCM / 16-bit PCM -> float32
51
77
  ```
@@ -63,6 +89,26 @@ Typed authored-SFX tail decoding is deliberately pinned to bank generator
63
89
  version 150. Recognized Event Actions are accepted only when the whole body
64
90
  is consumed; unknown, truncated, other-version, or trailing-byte bodies retain
65
91
  their shallow action type/target and raw payload, with `action: null`.
92
+ The v150 Voice Pitch, Volume, Bus Volume, LPF, and HPF action sets retain their
93
+ wwiser-corroborated element Set/Reset and available All/All-Except Reset
94
+ aliases. The inspected EVE CCP build 3453885 `Common.bnk` uses 47 LPF/HPF
95
+ actions, all
96
+ game-object-scoped element actions with non-bus targets; the broader aliases
97
+ remain structurally decoded so future banks do not lose valid action data.
98
+ The same bank uses 22 global element Bus Volume actions across 11 events:
99
+ 21 Sets and one Reset targeting the `Music` and `Engines_Warp` buses. The
100
+ object-scoped Set/Reset and global Reset All/All-Except aliases remain decoded;
101
+ the nonexistent v150 game-object Reset All/All-Except aliases remain
102
+ unsupported.
103
+ Their runtime policy is owned by `runtime-audio`, not this container reader.
104
+ Exact v150 STMG chunks attach `globalSettings` to an inspection and expose
105
+ state groups and custom transitions, switch groups and graph points, RTPC
106
+ defaults and ramp policies, built-in parameter bindings, acoustic textures,
107
+ and the global voice/filter settings. Numeric enum values and both directional
108
+ ramp values are retained even when current EVE events do not exercise them.
109
+ Invalid, duplicate, truncated, other-version, or trailing-byte STMG payloads
110
+ leave `globalSettings: null`; their raw chunk records remain available in
111
+ `chunks`.
66
112
  `nodes` contains playable Sound, Random/Sequence, Switch/State, and Layer
67
113
  objects. The separate `nodeBases` map preserves common authored properties
68
114
  and positioning facts for playable nodes and Actor-Mixers.
@@ -79,6 +125,21 @@ layer does not infer a numeric maximum radius from an attenuation curve. Like
79
125
  `eventMediaFromBanks`, `sfxNodesFromBanks` is consumer-facing graph
80
126
  interpretation; the resource lifecycle never calls it.
81
127
 
128
+ `busNodesFromBanks` recognizes only v150 HIRC 8 Audio Bus and HIRC 18
129
+ Auxiliary Bus records. It preserves the complete qualified body: ancestry and
130
+ root output device, the initial property bundle (including absent versus
131
+ authored-zero gain values), positioning and auxiliary targets, bus policy and
132
+ channel configuration, HDR settings, duck rules, ordered effect and metadata
133
+ references, RTPC curves, and state values. HIRC 19 is an LFO in this version
134
+ and is not treated as a bus. The typed records preserve authored facts; they do
135
+ not claim runtime mixing, ducking, or plug-in realization.
136
+
137
+ `effectNodesFromBanks` recognizes v150 HIRC 16 Fx ShareSet and HIRC 17 Fx
138
+ Custom records. It preserves the plug-in identity and opaque parameter block,
139
+ media index-to-source mappings, RTPC curves, state values, and initial plug-in
140
+ property values. Opaque parameter bytes are intentional: a consumer must
141
+ qualify each plug-in's DSP behavior before interpreting them.
142
+
82
143
  ## Related documentation
83
144
 
84
145
  - [Format subpaths](README.md)
@@ -45,6 +45,16 @@ Base runtime resource handle that carries normalized path/extension/requirement
45
45
  - Visibility: Public
46
46
  - Kind: Adapted Carbon concept
47
47
 
48
+ <!-- class:CjsLoadingObject -->
49
+ ## `CjsLoadingObject`
50
+
51
+ Resource-compatible handler whose public loading result is the constructed object produced by an extension route.
52
+
53
+ - Export: `@carbonenginejs/runtime-resource`
54
+ - Source: `src/resource/CjsLoadingObject.js`
55
+ - Visibility: Public
56
+ - Kind: Original CarbonEngineJS class
57
+
48
58
  <!-- class:CjsResManMainThreadLoader -->
49
59
  ## `CjsResManMainThreadLoader`
50
60
 
@@ -89,6 +89,16 @@ Bounds-aware little-endian cursor used for exact Wwise v150 NodeBase, authored-S
89
89
  - Visibility: Internal
90
90
  - Kind: Internal implementation class
91
91
 
92
+ <!-- class:GlobalSettingsCursor -->
93
+ ## `GlobalSettingsCursor`
94
+
95
+ Bounds-aware little-endian cursor over one Wwise Global Settings payload.
96
+
97
+ - Export: `None`
98
+ - Source: `src/formats/bnk/core/globalSettings.js`
99
+ - Visibility: Internal
100
+ - Kind: Internal implementation class
101
+
92
102
  <!-- class:ActionCursor -->
93
103
  ## `ActionCursor`
94
104
 
@@ -667,6 +677,28 @@ LSB-first bit reader over one Vorbis packet's bytes for the pure-JS Vorbis decod
667
677
  - Visibility: Internal
668
678
  - Kind: Internal implementation class
669
679
 
680
+ ### pickle
681
+
682
+ <!-- class:CjsPickleFormat -->
683
+ ## `CjsPickleFormat`
684
+
685
+ Data-only Python pickle format facade that currently decodes protocol 0 into JSON-compatible values or identity-preserving payload graphs while rejecting callable and object-construction opcodes.
686
+
687
+ - Export: `@carbonenginejs/runtime-resource/formats/pickle`
688
+ - Source: `src/formats/pickle/CjsPickleFormat.js`
689
+ - Visibility: Public
690
+ - Kind: Original CarbonEngineJS class
691
+
692
+ <!-- class:CjsPickleProtocol0Reader -->
693
+ ## `CjsPickleProtocol0Reader`
694
+
695
+ Construction-bound decoder for the inert data subset of Python pickle protocol 0.
696
+
697
+ - Export: `None`
698
+ - Source: `src/formats/pickle/core/CjsPickleProtocol0Reader.js`
699
+ - Visibility: Internal
700
+ - Kind: Internal implementation class
701
+
670
702
  ### png
671
703
 
672
704
  <!-- class:CjsPngFormat -->
@@ -749,62 +781,22 @@ WAV audio format profile that inspects RIFF chunk metadata and reads supported W
749
781
 
750
782
  ### shared effect layer
751
783
 
752
- <!-- class:ReflectionBlobStore -->
753
- ## `ReflectionBlobStore`
754
-
755
- Content-addressed arena that deduplicates every exact byte payload referenced by portable effect reflection.
756
-
757
- - Export: `None`
758
- - Source: `src/format/effect/effectReflectionPackage.js`
759
- - Visibility: Internal
760
- - Kind: Internal implementation class
761
-
762
784
  ### webgl
763
785
 
764
786
  <!-- class:CjsWebglFormat -->
765
787
  ## `CjsWebglFormat`
766
788
 
767
- WebGL shader format profile that translates compiled Carbon effects into CEWG packages carrying GLSL programs and portable source reflection.
789
+ WebGL shader format profile that translates compiled Carbon effects into Carbon v15 containers carrying GLSL programs and a per-pass backend block.
768
790
 
769
791
  - Export: `@carbonenginejs/runtime-resource/formats/webgl`
770
792
  - Source: `src/formats/webgl/CjsWebglFormat.js`
771
793
  - Visibility: Public
772
794
  - Kind: Original CarbonEngineJS class
773
795
 
774
- <!-- class:CewgPackage -->
775
- ## `CewgPackage`
776
-
777
- Reader for the flat CEWG container: chunk lookup, cached JSON decoding, and validated portable reflection access.
778
-
779
- - Export: `None`
780
- - Source: `src/formats/webgl/core/cewg/CewgPackage.js`
781
- - Visibility: Internal
782
- - Kind: Internal implementation class
783
-
784
- <!-- class:CewgPackageBuilder -->
785
- ## `CewgPackageBuilder`
786
-
787
- Builds a CEWG container from ordered, uniquely tagged chunks.
788
-
789
- - Export: `None`
790
- - Source: `src/formats/webgl/core/cewg/CewgPackageBuilder.js`
791
- - Visibility: Internal
792
- - Kind: Internal implementation class
793
-
794
- <!-- class:WebglReader -->
795
- ## `WebglReader`
796
-
797
- Bounded little-endian byte cursor over CEWG container bytes.
798
-
799
- - Export: `None`
800
- - Source: `src/formats/webgl/core/cewg/binary.js`
801
- - Visibility: Internal
802
- - Kind: Internal implementation class
803
-
804
796
  <!-- class:WebglReadError -->
805
797
  ## `WebglReadError`
806
798
 
807
- Error raised when CEWG bytes or package documents are malformed or inconsistent.
799
+ Error raised when container bytes or their backend blocks are malformed or inconsistent.
808
800
 
809
801
  - Export: `None`
810
802
  - Source: `src/formats/webgl/core/errors.js`
@@ -846,27 +838,27 @@ Formats DXBC operands, swizzles, and modifiers as GLSL expressions.
846
838
  <!-- class:CjsWebgpuFormat -->
847
839
  ## `CjsWebgpuFormat`
848
840
 
849
- WebGPU shader format profile that translates compiled Carbon effects into CEWGPU packages carrying WGSL programs, bind-group layouts, and portable source reflection.
841
+ WebGPU shader format profile that translates compiled Carbon effects into Carbon WebGPU containers carrying WGSL programs and bind-group layouts.
850
842
 
851
843
  - Export: `@carbonenginejs/runtime-resource/formats/webgpu`
852
844
  - Source: `src/formats/webgpu/CjsWebgpuFormat.js`
853
845
  - Visibility: Public
854
846
  - Kind: Original CarbonEngineJS class
855
847
 
856
- <!-- class:CewgpuContainer -->
857
- ## `CewgpuContainer`
848
+ <!-- class:CarbonWebgpuContainer -->
849
+ ## `CarbonWebgpuContainer`
858
850
 
859
851
  Reader over one WebGPU effect container.
860
852
 
861
853
  - Export: `None`
862
- - Source: `src/formats/webgpu/core/cewgpu/CewgpuContainer.js`
854
+ - Source: `src/formats/webgpu/core/carbonWebgpu/CarbonWebgpuContainer.js`
863
855
  - Visibility: Internal
864
856
  - Kind: Internal implementation class
865
857
 
866
858
  <!-- class:WebgpuReadError -->
867
859
  ## `WebgpuReadError`
868
860
 
869
- Error raised when CEWGPU bytes or package documents are malformed or inconsistent.
861
+ Error raised when Carbon WebGPU bytes or package documents are malformed or inconsistent.
870
862
 
871
863
  - Export: `None`
872
864
  - Source: `src/formats/webgpu/core/errors.js`
@@ -934,7 +926,7 @@ LSB-first bit writer that assembles repacked Wwise Vorbis packets into standard
934
926
  <!-- class:CjsYamlFormat -->
935
927
  ## `CjsYamlFormat`
936
928
 
937
- YAML format profile that parses YAML text into payload, JSON-graph, raw, or document output with configurable tag policies, alias limits, and identity/reference markers.
929
+ YAML format profile that parses YAML text or strict UTF-8 bytes into payload, JSON-graph, raw, or document output with configurable tag policies, alias limits, and identity/reference markers.
938
930
 
939
931
  - Export: `@carbonenginejs/runtime-resource/formats/yaml`
940
932
  - Source: `src/formats/yaml/CjsYamlFormat.js`
@@ -48,7 +48,7 @@ Data record mirroring Carbon's per-LOD decal range, holding the start index and
48
48
  <!-- class:Tr2EffectRes -->
49
49
  ## `Tr2EffectRes`
50
50
 
51
- Resource record that owns an effect package, resolves global and local permutation options, hydrates exact portable reflection into canonical shaders, and caches them by body index.
51
+ Resource record that owns an effect package, resolves global and local permutation options, reads a Carbon v15 container through `DoLoad(bytes)`, hydrates canonical shaders through `Tr2Shader.fromCarbonBinary(reader, index)`, and caches them by body index.
52
52
 
53
53
  - Export: `@carbonenginejs/runtime-resource`
54
54
  - Source: `src/resource/shader/Tr2EffectRes.js`
@@ -158,7 +158,7 @@ Canonical device-free sampler reflection record preserving static/dynamic setup
158
158
  <!-- class:Tr2Shader -->
159
159
  ## `Tr2Shader`
160
160
 
161
- Canonical device-free hydrated shader graph and top-level portable-reflection orchestrator.
161
+ Canonical device-free shader graph, built from one Carbon description record by `fromCarbonBinary(reader, index)`.
162
162
 
163
163
  - Export: `@carbonenginejs/runtime-resource/resource/shader`
164
164
  - Source: `src/resource/shader/Tr2Shader.js`
@@ -78,10 +78,94 @@ and urgent-membership semantics.
78
78
 
79
79
  ## Registration
80
80
 
81
- Format classes own input extensions. Resource classes are registered by a
82
- semantic requirement, never by file extension:
81
+ The Carbon-shaped primary route binds an extension to a resource-compatible
82
+ handler and a format. The handler declares whether the public result is a
83
+ stable resource or a constructed object:
83
84
 
84
85
  ```js
86
+ import {
87
+ CjsLoadingObject,
88
+ CjsResMan
89
+ } from "@carbonenginejs/runtime-resource";
90
+ import { CjsBlackFormat } from "@carbonenginejs/runtime-resource/formats/black";
91
+ import { CjsRedFormat } from "@carbonenginejs/runtime-resource/formats/red";
92
+
93
+ const resMan = new CjsResMan({ source });
94
+
95
+ resMan.RegisterExtension(".red", CjsLoadingObject, [
96
+ CjsBlackFormat,
97
+ CjsRedFormat
98
+ ]);
99
+ resMan.RegisterExtension(".black", CjsLoadingObject, [
100
+ CjsBlackFormat,
101
+ CjsRedFormat
102
+ ]);
103
+ ```
104
+
105
+ Ordered arrays apply request output/media filters first, then evaluate support
106
+ probes in order. The first supported format wins. One format without a probe
107
+ may be the final fallback; it cannot precede another entry. After selection,
108
+ reader failure is final and does not advance to the fallback. Both `.red` and
109
+ `.black` therefore use Black magic first and Red/YAML otherwise, independent
110
+ of the suffix.
111
+
112
+ A fixed `Target` may hydrate parsed values through its static `from` or
113
+ `fromYAML` method. `Identify(values, context)` may instead return a target
114
+ constructor, `true` to accept the reader result unchanged, or false/null to
115
+ fail. `Target` and `Identify` are mutually exclusive and only valid for object
116
+ handlers. These functions remain on the main thread even when the selected
117
+ format is worker-safe.
118
+
119
+ The normalized context supplied to formats as the third
120
+ `read(input, options, context)` argument, direct object loaders, `Identify`,
121
+ and `fromYAML` contains the same resource identity fields:
122
+
123
+ - `ext`: normalized lowercase extension without a leading dot;
124
+ - `resFilePath`: normalized lowercase logical resource path;
125
+ - `fileName`: normalized lowercase final path component; and
126
+ - `url`: the exact translated URL used by a URL-backed source, or `null` for
127
+ sources that read logical resource paths directly.
128
+
129
+ `path` remains a compatibility alias for `resFilePath`. URL text is not
130
+ lowercased independently: paths translated from `res:/` already use the
131
+ normalized resource path, while configured URL-base or resolver casing is
132
+ preserved.
133
+
134
+ The single-format short form:
135
+
136
+ ```js
137
+ import { TriTextureRes } from "@carbonenginejs/runtime-resource/resource/texture";
138
+ import { CjsDdsFormat } from "@carbonenginejs/runtime-resource/formats/dds";
139
+
140
+ resMan.RegisterExtension("dds", TriTextureRes, CjsDdsFormat);
141
+ ```
142
+
143
+ is equivalent to:
144
+
145
+ ```js
146
+ resMan.RegisterExtension("dds", TriTextureRes, {
147
+ Format: CjsDdsFormat
148
+ });
149
+ ```
150
+
151
+ `Register({ extensions })` accepts the same route objects keyed by extension.
152
+ Re-registration replaces the route for future uncached handles; an existing
153
+ canonical handle retains the complete route it captured.
154
+
155
+ The older registries remain independent compatibility and specialization
156
+ seams. `RegisterFormat` adds a format under its self-declared input extensions.
157
+ `RegisterResourceType` selects a resource class from a semantic requirement or
158
+ payload and takes precedence over the extension handler:
159
+
160
+ ```js
161
+ import { CjsResMan } from "@carbonenginejs/runtime-resource";
162
+ import {
163
+ Tr2ImageRes,
164
+ TriTextureRes
165
+ } from "@carbonenginejs/runtime-resource/resource/texture";
166
+ import { CjsDdsFormat } from "@carbonenginejs/runtime-resource/formats/dds";
167
+ import { CjsPngFormat } from "@carbonenginejs/runtime-resource/formats/png";
168
+
85
169
  const resMan = new CjsResMan().Register({
86
170
  source,
87
171
  formats: [ CjsDdsFormat, CjsPngFormat ],
@@ -99,8 +183,8 @@ const image = resMan.GetResource("res:/image/ship.png", {
99
183
  ```
100
184
 
101
185
  Those are distinct resource identities but share the normalized source-byte
102
- operation. The manager does not expose an extension-to-resource compatibility
103
- registry.
186
+ operation. `RegisterObjectLoader` remains the direct legacy byte-to-value
187
+ registration for an extension without an explicit route.
104
188
 
105
189
  ## Related documentation
106
190
 
@@ -95,6 +95,13 @@ Black `json` and `payload` outputs are worker-enabled; Black document/runtime
95
95
  outputs remain on the caller thread because structured cloning would discard
96
96
  their class identity.
97
97
 
98
+ Resource-backed format methods receive `(input, options, context)`. The
99
+ clone-safe context crosses the worker boundary with its normalized lowercase
100
+ `resFilePath`, `ext`, and `fileName`, its compatible `path` alias, and the
101
+ exact translated `url` used by a URL-backed source (or `null` for structural
102
+ sources). Direct descriptor reads that are not attached to a resource receive
103
+ `null` for the third argument.
104
+
98
105
  A declaration may restrict clone-safe outputs:
99
106
 
100
107
  ```js
package/package.json CHANGED
@@ -1,63 +1,63 @@
1
1
  {
2
- "name": "@carbonenginejs/runtime-resource",
3
- "version": "0.12.2",
4
- "description": "CarbonEngineJS resource lifecycle, cache, source, and object loading contracts.",
5
- "type": "module",
6
- "exports": {
7
- ".": "./dist/index.js",
8
- "./resource": "./dist/resource/index.js",
9
- "./resource/audio": "./dist/resource/audio/index.js",
10
- "./resource/geometry": "./dist/resource/geometry/index.js",
11
- "./resource/geometry/granny": "./dist/resource/geometry/granny/index.js",
12
- "./resource/shader": "./dist/resource/shader/index.js",
13
- "./resource/texture": "./dist/resource/texture/index.js",
14
- "./worker": "./dist/worker/CjsResManWorker.js",
15
- "./format": "./dist/format/index.js",
16
- "./formats": "./dist/formats/index.js",
17
- "./formats/black": "./dist/formats/black/index.js",
18
- "./formats/black/schema": "./dist/formats/black/core/blackSchema.js",
19
- "./formats/black/enums": "./dist/formats/black/core/blackEnums.js",
20
- "./formats/black/version": "./dist/formats/black/core/blackVersion.js",
21
- "./formats/bnk": "./dist/formats/bnk/index.js",
22
- "./formats/cmf": "./dist/formats/cmf/index.js",
23
- "./formats/dds": "./dist/formats/dds/index.js",
24
- "./formats/dxbc": "./dist/formats/dxbc/index.js",
25
- "./formats/hlsl": "./dist/formats/hlsl/index.js",
26
- "./formats/hlsl/portable": "./dist/formats/hlsl/portable.js",
27
- "./formats/webgl": "./dist/formats/webgl/index.js",
28
- "./formats/webgpu": "./dist/formats/webgpu/index.js",
29
- "./formats/fbx": "./dist/formats/fbx/index.js",
30
- "./formats/flac": "./dist/formats/flac/index.js",
31
- "./formats/gif": "./dist/formats/gif/index.js",
32
- "./formats/gltf": "./dist/formats/gltf/index.js",
33
- "./formats/gr2": "./dist/formats/gr2/index.js",
34
- "./formats/jpeg": "./dist/formats/jpeg/index.js",
35
- "./formats/mp3": "./dist/formats/mp3/index.js",
36
- "./formats/mp4": "./dist/formats/mp4/index.js",
37
- "./formats/obj": "./dist/formats/obj/index.js",
38
- "./formats/ogg": "./dist/formats/ogg/index.js",
39
- "./formats/png": "./dist/formats/png/index.js",
40
- "./formats/red": "./dist/formats/red/index.js",
41
- "./formats/red/schema": "./dist/formats/red/core/blackDefinitions.js",
42
- "./formats/stl": "./dist/formats/stl/index.js",
43
- "./formats/tga": "./dist/formats/tga/index.js",
44
- "./formats/wav": "./dist/formats/wav/index.js",
45
- "./formats/webm": "./dist/formats/webm/index.js",
46
- "./formats/webp": "./dist/formats/webp/index.js",
47
- "./formats/wem": "./dist/formats/wem/index.js",
48
- "./formats/yaml": "./dist/formats/yaml/index.js"
49
- },
50
- "sideEffects": false,
51
- "engines": {
52
- "node": ">=18"
53
- },
54
- "dependencies": {
55
- "@carbonenginejs/runtime-utils": "^0.1.3",
56
- "meshoptimizer": "^1.2.0",
57
- "yaml": "^2.4.0"
58
- },
59
- "license": "MIT",
60
- "publishConfig": {
61
- "access": "public"
62
- }
2
+ "name": "@carbonenginejs/runtime-resource",
3
+ "version": "0.14.0",
4
+ "description": "CarbonEngineJS resource lifecycle, cache, source, and object loading contracts.",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./dist/index.js",
8
+ "./resource": "./dist/resource/index.js",
9
+ "./resource/audio": "./dist/resource/audio/index.js",
10
+ "./resource/geometry": "./dist/resource/geometry/index.js",
11
+ "./resource/geometry/granny": "./dist/resource/geometry/granny/index.js",
12
+ "./resource/shader": "./dist/resource/shader/index.js",
13
+ "./resource/texture": "./dist/resource/texture/index.js",
14
+ "./worker": "./dist/worker/CjsResManWorker.js",
15
+ "./format": "./dist/format/index.js",
16
+ "./formats": "./dist/formats/index.js",
17
+ "./formats/black": "./dist/formats/black/index.js",
18
+ "./formats/black/schema": "./dist/formats/black/core/blackSchema.js",
19
+ "./formats/black/enums": "./dist/formats/black/core/blackEnums.js",
20
+ "./formats/black/version": "./dist/formats/black/core/blackVersion.js",
21
+ "./formats/bnk": "./dist/formats/bnk/index.js",
22
+ "./formats/cmf": "./dist/formats/cmf/index.js",
23
+ "./formats/dds": "./dist/formats/dds/index.js",
24
+ "./formats/dxbc": "./dist/formats/dxbc/index.js",
25
+ "./formats/hlsl": "./dist/formats/hlsl/index.js",
26
+ "./formats/webgl": "./dist/formats/webgl/index.js",
27
+ "./formats/webgpu": "./dist/formats/webgpu/index.js",
28
+ "./formats/fbx": "./dist/formats/fbx/index.js",
29
+ "./formats/flac": "./dist/formats/flac/index.js",
30
+ "./formats/gif": "./dist/formats/gif/index.js",
31
+ "./formats/gltf": "./dist/formats/gltf/index.js",
32
+ "./formats/gr2": "./dist/formats/gr2/index.js",
33
+ "./formats/jpeg": "./dist/formats/jpeg/index.js",
34
+ "./formats/mp3": "./dist/formats/mp3/index.js",
35
+ "./formats/mp4": "./dist/formats/mp4/index.js",
36
+ "./formats/obj": "./dist/formats/obj/index.js",
37
+ "./formats/ogg": "./dist/formats/ogg/index.js",
38
+ "./formats/pickle": "./dist/formats/pickle/index.js",
39
+ "./formats/png": "./dist/formats/png/index.js",
40
+ "./formats/red": "./dist/formats/red/index.js",
41
+ "./formats/red/schema": "./dist/formats/red/core/blackDefinitions.js",
42
+ "./formats/stl": "./dist/formats/stl/index.js",
43
+ "./formats/tga": "./dist/formats/tga/index.js",
44
+ "./formats/wav": "./dist/formats/wav/index.js",
45
+ "./formats/webm": "./dist/formats/webm/index.js",
46
+ "./formats/webp": "./dist/formats/webp/index.js",
47
+ "./formats/wem": "./dist/formats/wem/index.js",
48
+ "./formats/yaml": "./dist/formats/yaml/index.js"
49
+ },
50
+ "sideEffects": false,
51
+ "engines": {
52
+ "node": ">=18"
53
+ },
54
+ "dependencies": {
55
+ "@carbonenginejs/runtime-utils": "^0.1.3",
56
+ "meshoptimizer": "^1.2.0",
57
+ "yaml": "^2.4.0"
58
+ },
59
+ "license": "MIT",
60
+ "publishConfig": {
61
+ "access": "public"
62
+ }
63
63
  }