A native sOU HUD package is a ZIP archive with the ending .souhud. It contains a manifest and static browser files. With the package tool, you can check your HUD before installation. This chapter describes the supported fields, version rules, and file limits.
Directory structure
mein-hud/
hud.json
wwwroot/
index.html
hud.js
hud.css
panel.json
logo.png
fonts/
images/
licenses/hud.json is located directly at the archive root. The starting point is always wwwroot/index.html. panel.json, logo, own scripts and other directories are optional. For Blazor, the full published wwwroot output including _framework is included in the package. The higher-level project folder, bin, obj, development accesses and private configurations do not belong in it.
The package tool picks up the files of the specified folder; it is not a filter for accidentally enclosed source or secret files. Therefore, have your own clean package folder ready. The manifest must not be hidden in an additional ZIP subfolder.
Maintain the description, author, author/imprint/privacy URLs and localized preview, gallery and demo files when creating or editing the HUD entry. They are stored separately in the cloud and do not add fields to hud.json.
Manifest fields explained
{
"id": "mein-cast-hud",
"version": "1.2.0",
"name": "Mein Cast HUD",
"apiVersion": 2,
"runtime": "web",
"entryPoint": "index.html",
"logo": "logo.png",
"infoUrl": "https://example.com/mein-hud",
"outlineColors": {
"ct": "#6FA8DC",
"t": "#E8B44C"
},
"subviews": [
{ "name": "Vor dem Match", "route": "views/prematch" },
{ "name": "Vollbild", "route": "views/fullscreen" }
]
}| Field | Type and obligation | Rules |
|---|---|---|
id | String, required | 1–64 character; starts with small ASCII letter, then small letters, numerals or hyphen. Model ^[a-z][a-z0-9-]{0,63}$. |
version | String, required | Three numerical components, optionally a suffix of small letters, numbers and hyphens. Model ^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9-]+)?$. Examples: 1.0.0, 1.0.1-preview. |
name | String, required | 1–100 sign. Visible name in the HUD administration. |
apiVersion | Integer, required | Exactly 2. Designates the schema, not SDK or package version. |
runtime | String, required | web, blazor-wasm or lhm. Native own HUDs use one of the first two variants; lhm is the compatibility format. |
entryPoint | String, required | Exact index.html; file must exist under wwwroot. |
logo | String or null, optional | Secure relative file path under wwwroot, without leading wwwroot/. PNG, JPG, JPEG or WebP; file must exist. |
infoUrl | String or null, optional | Complete HTTP or HTTPS address of the creator's website, up to 2048 characters, without whitespace, control characters or embedded credentials. Appears as More information for installed HUDs and opens in the browser only when clicked. Omit it or use null to hide the link. Older desktops ignore this field; the updated local importer and the package tool built from this source validate it. |
releaseNotes | String or null, optional | Patch notes for this package version, up to 8000 UTF-16 code units. Line breaks and tabs are allowed; other control characters are rejected. On approval, the notes accompany the update sent to the enabled Discord destinations. Long texts appear in full across numbered messages. The overall manifest size limit also applies; missing notes are not invented. |
outlineColors | Object or null, optional | Contains both strings ct and t, each exactly #RRGGBB. The palette is available for the associated display of the CS2 outlines. |
subviews | Array, optional; standard [] | Each entry has name and route. Explicit null is invalid. |
subviews[].name | String, required in the entry | 1–100 characters; caption of the output in the manager. |
subviews[].route | String, required in the entry | Unique route under views/. Each segment begins with small letters and contains only small letters, numbers or hyphens. No final slashes. |
Native JSON property names are read without distinction of upper/lower case. Nevertheless, use the camelCase spelling shown. The values for runtime and entry must fit exactly. Additional manifest fields do not extend the functionality of sOU; use the fields described here for the integration.
Archive and path boundaries
| Check | Limitation or behaviour |
|---|---|
| Archive file and unpacked data | A maximum of 128 MiB each; the actual unpacked sum is additionally checked when writing. |
| Archive entries | At most 4.096 entries, including directory entries. |
| Manifest | Not more than 16.384 byte. |
| Panel definition | At most 65.536 bytes; additional section and field boundaries in Panel reference. |
| Relative paths | Not empty and shorter than 240 characters. Slash / separates segments. |
| Segmentation characters | ASCII letters, numerals, underscore, point, dollar sign, plus, at sign, space and hyphen. |
| Prohibited segments | Blank segments, ., .., final points/spaces and Windows device names such as CON, NUL, COM1 or LPT1, even before an extension. |
| Collisions and links | Duplicate paths are rejected regardless of upper case/low case. Symbolic links and reparse points are not allowed. |
Inner spaces in asset names are allowed, such as fonts/Meine Schrift.ttf. The import does not rename files. Browser addresses must correctly encode URL spaces; relative CSS and HTML references should fit exactly to the file. Absolute paths, back strokes, colons, alternative data streams and breakouts from the packet folder are not allowed.
Versions, identity and updates
The combination of id and version identifies an immutable packet level. The desktop rejects an already installed version. Therefore, do not replace file contents in an existing installation or an already distributed archive under the same version number. Increase the version for changes and import the new package.
The three numbers are compared numerically. A version without suffix is above the same version with suffix. Purely numerical suffixes are compared numerically, other suffixes ordinal; a numerical suffix stands before a nonnumerical one. This is not a full SemVer contract: build metadata with +, points within the suffix and four-part version numbers are not allowed in the HUD Manifest.
Subscriptions and workspace shares refer to the HUD identifier. There is a current installed status for each HUD; when downloading online, sOU automatically determines the latest released packet with the numerical order described above. Updates are explicitly installed in the HUD overview. An already newer local installation cannot be downgraded by importing an older package. Already published archives remain unchangeable.
Output addresses and subviews
| Address | Utilisation |
|---|---|
/huds/{id}/ | Stable public entry into the main view. Select the offered package status when loading. |
/huds/{id}/views/prematch | Stable entry into an explicitly declared subview. |
/hud-packages/{id}/{version}/ | Version-bound inner address of a native package. |
/compat/huds/{id}/{version}/ | Version-bound inner address of a LHM/JT package. |
The stable address loads the current installed stand in a transparent frame. An already opened document thus remains at its status; an import does not exchange its files or panel definition in the middle of the cast. Required older files are held until the end of their use and then removed. The previous package addresses are not a selection of additional installations: If an older version is no longer loaded, its entry HTML address leads to the current HUD; missing old assets still provide an error instead of content from another version. For an update of the current source, reload it consciously. After a local service restart, a reloaded browser or OBS page reloads its current stable entry as soon as the service is reachable again.
Subviews are views of the same application. The host also delivers the packet index.html there and sets the base address to the common packet root. Your HUD evaluates the route itself. An additional subfolder index.html is not the contract for this. Undeclared routes are rejected. Main view and subviews share the same packet identity, media base, and panel configuration.
Building and testing
First, set up the tool via NuGet as described under Setting up templates and tools. The following commands use this working directory with werkzeuge and ausgabe. Place your package folder mein-hud or the original archive to be normalized next to it.
./werkzeuge/sou-hud pack ./mein-hud ./ausgabe/mein-hud-1.2.0.souhud
./werkzeuge/sou-hud validate ./ausgabe/mein-hud-1.2.0.souhud
./werkzeuge/sou-hud normalize ./original-lhm.zip ./ausgabe/mein-lhm.souhudThe output file must be outside the input folder and must not yet exist. pack checks the generated archive before the output. normalize transfers a compatible original archive into the native sOU format and is particularly relevant before a cloud upload. Locally, a LHM-/JT-ZIP can be imported directly. Further rules under LHM/JT import.
Installation and typical rejections
A new version appears only after successful examination of manifest, entry, logo and panel in the installed HUDs. If rejected, correct the package and import it again. After installation, also check the display in the browser and in OBS: A valid package structure alone does not yet confirm that your HUD correctly displays all game states.
- Put ‘hud.json missing’: manifest to the archive root, not the parent folder.
- ‘HUD entry file missing’:
wwwroot/index.html; for WebAssembly use the Publish output. - “This version of HUD is already installed”: New version. Do not use the same IDs for technically different HUDs.
- ‘Invalid or duplicate packet path’: Remove colliding file names, unauthorized characters and links; case/case lettering alone does not create a second file.
- Check Panel rejected: identifiers, field types, selection values and limits against Panel reference.
- Check Empty output for valid package: browser console, relative assets, SDK order and waiting display without GSI.
File access and resources
Native packages are delivered with a content security policy limited to local resources. Local scripts and WASM are possible; font files belong in the package. Images can be local files or allowed data URLs. The LHM compatibility profile has its own rules for HTTPS presentation resources, described under External legacy resources.
Package files are not the location for runtime settings. Panel values and imported media manages sOU outside of the immutable installation. Edit this data through the manager and receive it through the SDK. If a cloud permission is revoked, new outputs may be blocked; it does not automatically exchange a current output.