Publishing on the Steam Workshop

Anything you can drop in mods/ can be published on the Steam Workshop, and a subscriber has nothing to copy: Steam downloads the item, and the game reads it straight from Steam’s own download folder.

Ten minutes the first time, two minutes afterwards. The one thing to accept up front: Steam has no button for uploading Workshop items. The only channel is SteamCMD, Valve’s small command-line tool. It is the same for every game on Steam.

How an item reaches a player

The subscriber copies nothing. Their own mods/ folder still wins on a name clash.

1. Put your content in a folder

A Workshop item is a folder, not a file — even when it holds a single circuit. Create one anywhere on your disk. Its layout mirrors mods/, so one authoring format serves both channels:

MyItem/
  my_pack.db               ← a mod pack
  circuits/monaco.circuit  ← a circuit (or at the item root)
  lang/pl.txt              ← a language pack (or pl.txt at the root)

Everything is optional and one item may carry all three. A file at the item root is only read as a language when its name has the shape of a language code, so a readme.txt next to it is left alone.

Then add a preview image next to the folder, not inside it: a PNG or JPG, under 1 MB. A screenshot of the editor, or of the track, is fine.

2. Install SteamCMD

From Valve: developer.valvesoftware.com/wiki/SteamCMD.

Windows — unzip steamcmd.exe into a folder of its own and run it once so it updates itself.
Linux — install the steamcmd package, or unpack the tarball.

3. Write `item.vdf`

A small text file, next to your folder. Change the paths and the title:

"workshopitem"
{
    "appid"           "4514930"
    "publishedfileid" "0"
    "contentfolder"   "C:\\Users\\me\\Workshop\\MyItem"
    "previewfile"     "C:\\Users\\me\\Workshop\\preview.png"
    "title"           "Monaco 1994"
    "description"     "A tight street circuit, 3.3 km, 19 turns."
    "changenote"      "First release."
    "visibility"      "0"
}

Field	Notes
`appid`	`4514930` — The Undercut. Never change it
`publishedfileid`	`0` creates a new item. After the first upload, SteamCMD writes the real id here for you
`contentfolder`	Absolute path to your item folder. On Windows, double every backslash
`previewfile`	Absolute path to the image, under 1 MB. Optional — you can add it later on the item’s page
`visibility`	`0` public · `1` friends only · `2` hidden. Start hidden if you want to inspect the page first

4. Upload

In a terminal or command prompt, with the Steam account that owns the game:

steamcmd +login YOUR_STEAM_NAME +workshop_build_item "C:\Users\me\Workshop\item.vdf" +quit

It asks for your password and your Steam Guard code — it is interactive, so run it yourself rather than from a script. When it finishes it prints the item’s id and writes it into item.vdf.

Keep item.vdf. It is your key to the item: it is what makes the next upload an update instead of a duplicate. (SteamCMD rewrites the file and strips any comment you put in it, so keep your notes elsewhere.)

5. Accept the agreement, finish the page

Open the item’s Workshop page — Steam → Community → Workshop → The Undercut → Your files. On a first upload Steam asks you to accept the Workshop legal agreement, and the item stays invisible until you do. Title, description, images and tags are editable there from then on.

6. Check it works

Subscribe to your own item. Steam downloads it by itself; there is nothing to copy. Launch the game:

a pack appears in New Career → Custom Mods
a circuit appears in the career setup’s circuit lists
a language appears in Settings → Language

If it does not, run the game with --list-mods from its folder: it prints the Workshop folder it resolved, every subscribed item it found, and everything each scan picked up.

Updating a published item

Replace the files in the same folder, set a new changenote in item.vdf, and run the same command. Because publishedfileid now holds your item’s id, the item is updated in place — no duplicate, and subscribers get the new version automatically.

While you iterate, remember that a file in your own mods/ wins over the subscribed copy of the same name. That is how you test a change to something you have already published, without unsubscribing.

If something goes wrong

Symptom	What to check
”Failed to update workshop item”	Every path in `item.vdf` must be absolute and exist; the preview image must be under 1 MB
Login refused	SteamCMD is interactive — type the Steam Guard code when asked. The account must own the game
The item page is empty after an upload that errored	An id handed out by a create that then failed is a phantom: nothing was committed. Only an id you can open on the Workshop is real
The content does not show in the game	Check the extension (`.db`, `.circuit`, `.txt`) and its place in the item folder, then run `--list-mods`
Nothing works in the demo	The demo and Next Fest builds ship without mod support entirely