Ctrlk
WebsiteStoreDiscordYouTube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Adding Props

The catalogue is the base game's props. Your own go in beside them, and then they behave the same: a tile in the grid, a thumbnail, measurements in the viewer, an answer when another script asks what they are.

Two ways in, split by how many there are. A couple of props is a couple of lines you type; a whole pack is a tool that opens every model, renders a thumbnail and measures it.

A Prop or Two, by Hand

data/custom.json, one object each:

[
  { "model": "my_chair_01", "label": "Custom Chair", "category": "seating" },
  { "model": "my_lamp_01", "label": "Street Lamp", "category": "lighting", "tags": ["night"] }
]

  • tier defaults to prop; structure or element keeps it out of furnishing sessions

  • tags are what the picker's Where menu filters on

  • thumbnail: assets/custom/<model>.webp, or none and the tile draws empty

  • a model this server doesn't stream never appears, and says nothing about it

No tool touches this file, so what you type stays.

A Whole Pack, with the Tool

tools/prop-pack/ reads a prop resource, renders a thumbnail for every prop in it, measures what the viewer shows, and writes the rows.

What It Needs

  • Node 18 or newer

  • Blender 4.x with the Sollumz addon: Sollumz is the only thing that reads a .ydr

Neither has to be installed already:

That fetches a portable Blender and the current Sollumz release into tools/prop-pack/blender/, enables the addon in that copy, and stops. Nothing is registered with Windows, nothing needs an administrator, and deleting the folder undoes all of it. About 400 MB, which is why it is a flag rather than something the tool decides on its own.

Running It

Run this on your own machine, not on the live server. It wants Blender and a copy of the pack, and neither belongs on a machine that is serving players.

Copy the pack and the tools/prop-pack folder somewhere local, then:

Inside a resource it writes there; carried out on its own it writes into output/ beside itself, in the same shape. --out <path> puts it anywhere.

Copying It Across

Two things, into the server's rm_mapeditor:

  • data/custom/<pack>.json: the pack's own file, which is nobody else's

  • the new files in assets/custom/: that folder holds every pack's thumbnails together

Then restart the resource. Nothing has to be merged: the server reads every file in data/custom/, and a pack that arrives twice is one entry rather than two. Removing a pack is deleting its file.

Options

Option
What

--pack <path>

the prop resource to read (required)

--out <path>

where to write; defaults to the resource this sits in, or output/ beside the tool

--category <name>

category for every prop in this pack (default misc)

--tier <name>

prop, structure or element

--tags <a,b>

tags for every prop

--size <px>

thumbnail size (default 256)

--jobs <n>

Blender processes at once (default 2)

--overwrite

re-render thumbnails that already exist

--dry-run

list what would be done and stop

--install

fetch Blender and Sollumz, then stop

--blender <path>

the executable, if it is somewhere this cannot find it

--tex <path>

a folder of textures, for the ones a pack asks for but does not carry

--codewalker <path> --gta <path>

export those textures out of the game itself

Editing What It Wrote

The pack's file is yours to edit. A second run keeps everything you typed, a label you rewrote, a category you moved a prop to, and only takes the measurements again, since those are the tool's answer and the pack may have changed under them.

Textures a Pack Doesn't Carry

Many packs reuse the game's own textures rather than shipping copies. Those surfaces come out plain grey in a thumbnail, and the run says which names were missing. The shape is still right.

If the machine has GTA V and a copy of CodeWalker, the tool can take those textures out of the game and render again:

Only the names a prop actually asked for are looked up, and what it finds is kept for the next pack that shares a texture. That cache is game art on the machine that owns the game: it isn't in a release.

When Something Goes Wrong

no .ydr files under ...: point --pack at the prop resource itself. The models usually sit in a stream/ subfolder, and it looks there on its own.

every model in ... is escrow-protected: the pack was uploaded to Keymaster and came back encrypted. Only the server it was sold to can read those, so no tool on this side opens one. Run this on the copy you made before uploading; a pack somebody else sells you can't be catalogued this way.

could not run Blender: run with --install, or pass --blender <path>.

A thumbnail is black or empty: the prop is glass, a decal, or something else with almost nothing opaque in it. The picker draws the tile either way and the prop places normally.