Steam Workshop

Publish your mods to Steam Workshop for easy distribution. Players can subscribe to mods and they're automatically downloaded and loaded.

Prerequisites

Before uploading, ensure your mod:

1. Builds successfully (npm run build)
2. Has a valid manifest.json with all required fields
3. Has a cover image for the Workshop listing
4. Is installed and working locally in the mods/ folder

Cover Image Requirements

Your Workshop listing needs a cover image for visibility:

Requirement	Value
Aspect ratio	16:9
Recommended size	1920×1080 px
Minimum size	640×360 px
Format	PNG or JPG
File name	Referenced in manifest.json cover field

Place the cover image in your project root (e.g. cover.png). The build process copies it to dist/.

{
    "cover": "cover.png"
}

Manifest Fields for Workshop

Add these fields to your manifest.json:

{
    "id": "my-awesome-mod",
    "name": "My Awesome Mod",
    "version": "1.0.0",
    "author": "YourName",
    "description": "A detailed description of what your mod does.",
    "apiVersion": 2,
    "permissions": ["events", "network"],
    "cover": "cover.png",
    "tags": ["quest", "network", "story"]
}

Field	Required	Description
id	Yes	Unique mod identifier
name	Yes	Display name on Workshop
version	Yes	Semantic version (shown to subscribers)
description	Yes	Workshop description
cover	Recommended	Path to preview image
tags	Recommended	Categories for browsing/filtering

Uploading

First Upload

1. Build your mod: npm run build
2. Install it locally: copy dist/ contents to mods/{mod-id}/
3. Launch the game
4. Open the Mods menu from the main menu
5. Find your mod in the Local Mods list
6. Click Upload to Workshop
7. Add a change note describing your mod (this is shown on the Workshop page)
8. Click Upload

The game reads your manifest.json and uses:

• name as the Workshop title
• description as the Workshop description
• cover as the preview image
• tags for categorization

After upload, a workshopId is automatically saved to your mod's data. This links future uploads to the same Workshop item.

Updating an Existing Mod

When you've made changes and want to push an update:

1. Bump the version in manifest.json (e.g. "1.0.0" → "1.1.0")
2. Rebuild: npm run build
3. Copy updated dist/ to mods/{mod-id}/
4. Launch the game → Mods menu
5. Your mod shows an Update indicator
6. Click Upload to Workshop
7. Add a change note describing what's new
8. Click Update

Subscribers receive the update automatically on their next game launch.

Subscribing to Mods

Players discover and install mods through:

1. In-game: Mods menu → Steam Workshop button → browse and subscribe
2. Steam client: Community → Workshop → HackHub → subscribe to items
3. Web browser: Visit the Steam Workshop page and click Subscribe

Subscribed mods are automatically downloaded and loaded on the next game start.

Local Priority System

If a local mod and a Workshop mod share the same id, the local mod takes priority:

• The Workshop version is not loaded
• The local version runs instead
• This is invisible to the player (they see one mod, not two)

This system enables:

• Development workflow: Test changes locally before publishing
• Custom overrides: Players can modify a Workshop mod locally
• Forking: Create a local variant of a published mod

To revert to the Workshop version, simply delete the local copy from mods/.

Workshop Item States

In the Mods menu, Workshop mods can show different states:

State	Meaning
Installed	Subscribed and loaded normally
Needs Update	Local version is older than the published version
Disabled	Player manually disabled this mod
Error	Mod failed to load (check console for details)

Troubleshooting

Upload Fails

• Ensure you're logged into Steam and own HackHub
• Check that manifest.json is valid JSON (no trailing commas)
• Verify the cover image exists and is readable
• Check your internet connection

Cover Image Not Showing

• Ensure it's referenced correctly in manifest.json cover field
• File must be PNG or JPG format
• File must be present in the mod folder (not just the project root)
• Try a smaller file size if upload times out

Mod Not Visible After Subscribe

• Restart the game (mods are loaded at startup)
• Check if a local mod with the same ID is overriding it
• Verify the mod's apiVersion is compatible with your game version
• Check the developer console for loading errors

Version Mismatch

If subscribers report issues after an update:

• Ensure you bumped the version field before uploading
• The game compares versions to detect updates
• Use semantic versioning: MAJOR.MINOR.PATCH