Mod API

The Rip N Ship Mod API lets creators add supported community content without changing the game itself. This page explains the formats the game currently understands, what each format can change, and how to package a working mod.

Version 0.8.18 reference

This page documents the Mod API included with Rip N Ship Early Access 0.8.18. The API is still evolving. A future game update may change or break part of this format, so always confirm your game version and check this page for the latest guide before creating, updating, or troubleshooting a mod.

What changed since the 0.8.9 reference

Creator Studio can now build Item projects: standalone image or binary GLB props that players buy from CardBay and place in their rooms. The .ripset schema remains version 1, and the ZIP-mod arcade and grading-provider interfaces listed below have not gained new content types.

Choose the correct format

Rip N Ship currently has two separate creator systems.

What you want to make	Format	How players install it
Custom card set and booster products	`.ripset`	Import through Creator Studio or subscribe in Workshop
One standalone custom card	`.ripset`	Import through Creator Studio or subscribe in Workshop
Main-room or Stream-room theme	`.ripset`	Import through Creator Studio or subscribe in Workshop
Movable CardBay room item using an image or GLB model	`.ripset`	Import through Creator Studio or subscribe in Workshop
Supported arcade game	ZIP with `mod.json`	Workshop Install Mod ZIP or Steam subscription
Grading-provider artwork	ZIP with `mod.json`	Workshop Install Mod ZIP or Steam subscription
Website tab, replacement for an existing prop, script, or gameplay plugin	Not currently supported	None

Use Creator Studio for cards, packs, effects, audio, room themes, and new CardBay room items. Use a ZIP mod for an arcade game or the limited grading-provider asset system.

Do not place a .ripset inside a normal mod ZIP for local installation. The two formats use different import paths.

Mod API compatibility

The Mod API is an Early Access feature rather than a permanently frozen standard.

A package that works in 0.8.18 may need an update after the game changes.
Test against the exact game version you plan to support.
Put that tested game version in your mod description or readme.
Keep every released ID stable when updating compatible content.
Increase your mod or project version when publishing an update.
Return to this page before updating an older project.

The version inside a package identifies your mod release. It does not force the game to reject an older or newer package automatically.

ZIP mods

A ZIP mod is a folder containing a mod.json manifest and the assets used by that manifest.

Folder layout

mod.json may be at the root of the ZIP:

text

my-mod.zip
├── mod.json
└── assets/
    └── icon.png

It may also be inside one top-level folder:

text

my-mod.zip
└── my-mod/
    ├── mod.json
    └── assets/
        └── icon.png

Do not bury mod.json under two or more folders. The local ZIP installer only checks the archive root and its immediate child folders.

Base manifest

json

{
  "id": "my-mod",
  "name": "My Mod",
  "version": "1.0.0",
  "description": "A short description of the mod.",
  "type": "arcade",
  "icon": "assets/icon.png"
}

Field	Required	Purpose
`id`	Yes	Permanent internal identity and install-folder name
`name`	Recommended	Player-facing name; falls back to the ID
`version`	Recommended	Mod release shown in Workshop; defaults to `1.0.0`
`description`	No	Workshop and creator description
`type`	Feature-specific	Arcade mods require `arcade`
`icon`	No	Relative path to an icon; also used as a Workshop preview when available
`arcade`	Arcade mods	Arcade settings described below
`gradingProvider`	Grading artwork	Limited provider-asset settings described below

Fields that are not recognized by a current feature do nothing. For example, adding a url field does not create a website tab.

ZIP mod IDs

A ZIP mod ID must:

contain 2 to 49 characters;
begin with a lowercase letter or number;
use only lowercase letters, numbers, and hyphens.

Valid IDs:

text

my-arcade-mod
homebrew1942
rns-demo

Invalid IDs:

text

My-Mod
my_mod
my.mod
m

Use a unique ID and never change it after releasing the mod. The game uses it to recognize updates and avoid collisions.

Static assets

Manifest asset paths are relative to the mod folder:

json

{
  "icon": "assets/icon.png"
}

Asset paths must stay inside that folder. A file included in the ZIP has no effect until a supported manifest field points to it.

ZIP mods do not run arbitrary JavaScript, HTML, CSS, DLLs, applications, or command files. They provide data and static assets to the features listed on this page.

Install a local ZIP

Start Rip N Ship.
Open Workshop from the main menu.
Expand Local File Tools.
Choose Install Mod ZIP.
Select the ZIP.
Let the game reload its window.

Use Open Mods Folder in the same screen to find the active local mod directory.

Typical locations are:

text

Windows: %APPDATA%\rip-n-ship\mods\
macOS:   ~/Library/Application Support/rip-n-ship/mods/
Linux:   ~/.config/rip-n-ship/mods/

The installer does not overwrite an existing local mod with the same ID. Uninstall the old local copy before installing its replacement.

Arcade mods

An arcade mod adds one game to the in-game arcade cabinet's game selector. The arcade cabinet becomes available at streamer level 40.

Complete example

text

my-homebrew-game/
├── mod.json
├── assets/
│   └── icon.png
└── roms/
    └── game.nes

json

{
  "id": "my-homebrew-game",
  "name": "My Homebrew Game",
  "version": "1.0.0",
  "description": "A custom game for the Rip N Ship arcade cabinet.",
  "type": "arcade",
  "icon": "assets/icon.png",
  "arcade": {
    "name": "My Homebrew Game",
    "rom": "roms/game.nes",
    "core": "nestopia",
    "platform": "NES"
  }
}

Zip the folder, install it through Workshop > Local File Tools, and open the cabinet's game selector.

Arcade fields

Field	Required	Behavior
`type`	Yes	Must be exactly `arcade`
`arcade.rom`	Yes	Relative path to the game file inside the mod
`arcade.core`	No	Emulator core; defaults to `mame2003_plus`
`arcade.name`	No	Cabinet display name; falls back to the mod name
`arcade.platform`	No	Custom platform label; otherwise inferred from the core

The game omits an arcade entry when the ROM is missing, the core is unsupported, the manifest is malformed, or the ROM path points outside the mod folder.

The manifest does not validate an arcade file by extension. The selected core still needs to support the actual file.

Supported cores

Core ID	Default label	Typical formats
`fbneo`	FBNeo Arcade	Arcade ROM sets
`mame2003_plus`	MAME Arcade	MAME 2003-Plus ROM sets
`pcsx_rearmed`	PlayStation 1	PS1 images supported by the core
`mednafen_psx_hw`	PlayStation 1	PS1 images supported by the core
`nestopia`	NES	NES ROMs
`snes9x`	SNES	SNES ROMs
`mgba`	Game Boy / GBA	GB, GBC, and GBA ROMs
`genesis_plus_gx`	Genesis / Mega Drive	Genesis and Mega Drive ROMs

Common file extensions include:

text

.zip .7z .nes .sfc .smc .gb .gbc .gba .md .gen .bin .cue .iso .chd .pbp

Compatibility depends on the selected core and file contents rather than the extension alone.

BIOS folder

The arcade manifest does not have a bios field. When a selected core needs BIOS data, the game looks in:

text

Documents/Rip N Ship Arcade/bios/

Common names include:

text

neogeo.zip
scph*.bin
ps1*.bin

Test an arcade mod

Install the ZIP from a clean local copy.
Confirm its name and icon appear in Workshop.
Confirm it appears in the cabinet selector.
Launch it with the selected core.
Test controls, audio, save behavior, and clean exit.
Restart Rip N Ship and test it again.
Record the exact Rip N Ship version used for testing.

Grading-provider assets

Grading-provider ZIPs are a limited asset feature. They are not a complete system for adding a new grading company.

Recognized fields

json

{
  "id": "example-grading-assets",
  "name": "Example Grading Assets",
  "version": "1.0.0",
  "type": "grading-provider",
  "gradingProvider": {
    "id": "example-grader",
    "logoAsset": "assets/logo.png",
    "frontAsset": "assets/slab-front.png",
    "backAsset": "assets/slab-back.png",
    "submissionKitAsset": "assets/submission-kit.png",
    "showcaseAsset": "assets/showcase.png"
  }
}

Field	Current use
`gradingProvider.id`	Permanent provider identity
`logoAsset`	Provider and Workshop artwork
`frontAsset`	Front of the slab; generic rendering needs front and back
`backAsset`	Back of the slab; generic rendering needs front and back
`submissionKitAsset`	Table kit art for an order already using this provider
`showcaseAsset`	Showcase art used by a supported provider flow

The gradingProvider object registers the asset provider. The top-level type in the example is descriptive and does not unlock more behavior.

Current limits

An arbitrary grading-provider mod does not create:

a new grading website or laptop tab;
a submission form;
grading prices or turnaround rules;
a new grading algorithm;
a route for creating orders with that provider.

PSA, Beckett, and CardCore use dedicated game flows. Treat the IDs psa, beckett, and cardcore as reserved.

For most community projects, use Creator Studio or an arcade ZIP rather than this limited asset interface.

Creator Studio `.ripset` mods

Creator Studio is the supported editor for custom cards, packs, single cards, room themes, and CardBay room items. It validates projects and exports a portable .ripset package.

Start with the Creator Studio overview, then use the Complete Card Set Guide and Odds, Slots & Pools for the full visual workflow.

Content types

Project type	What it adds
Card Set	Complete collection, printings, rarities, packs, odds, prices, effects, and optional room atmosphere
Single Card	One standalone loose CardBay card with no booster packs
Room Theme	Main-room background, Stream-room background, and/or background music
Item	One purchasable CardBay room prop using a 2D image or optional embedded GLB model

What a card-set project can change

A card-set .ripset can define:

project name, ID, Series, author, version, and description;
square set icon and shared card back;
card corner radius from 0% to 12%;
whether ripped cards remain stacked;
main-room and Stream-room backgrounds;
background music;
custom rarities, colors, sorting, weights, and reveal sounds;
base-card IDs, names, collector numbers, fronts, backs, and groups;
several printings or variants of one base card;
separate rarity, finish, image, value, weight, sound, and eligibility for each printing;
foil recipes, masks, textures, colors, and effect strengths;
several sealed products in one project;
up to 20 wrapper images and a pack-open sound per product;
appearance chance, rarity weights, group filters, allowlists, and duplicate protection per slot;
special alternate-pack rules with their own chance and replacement slots.

The existing Creator Studio articles explain how those parts interact. In particular, read Odds, Slots & Pools before tuning a release.

Stable IDs

Creator Studio project IDs may contain 1 to 64 characters. They must begin with a lowercase letter or number and may then use:

text

lowercase letters
numbers
periods
underscores
hyphens

Keep all released project, rarity, card, variant, product, slot, and special-rule IDs stable. Existing saves use them to recognize updated content.

Card image naming

Batch import understands patterns such as:

text

CST-001_Custom_Card__front.png
CST-001_Custom_Card__back.png
CST-001_Custom_Card__v-holo__front.png
CST-001_Custom_Card__v-reverse__front.png
CST-001_Custom_Card__v-alt-art__front.png

Use one collector number for the front, back, and all variants of the same base card.
__front and __back choose the image side.
__v-name creates a separate printing.
A card without its own back uses the shared project card back.
Files without a side marker can still import as fronts.

Recommended card art uses a 200:279 ratio, such as 800 x 1116 pixels. See Prepare the files for all current art sizes.

Card and printing behavior

A base card is the shared collectible identity. A printing is one pullable version of that card.

Each printing can have its own:

rarity and finish;
front-art override;
raw value and price source;
chance within its rarity;
reveal sound;
groups;
pack-eligible or promo-only state;
material recipe and effect assets.

The slot first chooses a rarity, then chooses among eligible printings in that rarity. A printing weight is not a direct whole-pack percentage.

Foil and material effects

Creator Studio currently includes material families such as:

Basic Foil Fallback;
Custom Holo;
Custom Reverse Holo;
Custom Rainbow;
Custom Textured Foil;
Silver, Satin, Magma, and Lore;
Vertical Wave and Sea Wave;
Glitter, Lava, and Tempest;
Free Form 1 and 2;
Calendar Wave and Rainbow Pillars;
High Gloss, Chrome Rainbow, and Metallic.

Depending on the selected recipe, a printing may use foil masks, texture masks, normal masks, pattern textures, top textures, colors, and effect-strength controls.

Use Creator Studio's material editor rather than hand-editing those values. The editor keeps the related settings together and provides a live preview.

Pack slots

Every Pack Slot can control:

Setting	Purpose
Appearance chance	Whether the position appears in the pack
Rarity weights	Relative chance of each eligible rarity
Group or pool	Restricts the eligible card group
Printing allowlist	Restricts the eligible printing IDs
Duplicate protection	Avoids the same base card when the pool is large enough

A printing needs positive weight, the chosen rarity, matching groups or allowlists, and pack eligibility before a slot can pull it.

Special-pack rules

A special rule can replace selected normal slots with a different rarity mix and pool. Use it for alternate collation such as a jackpot pack.

Each rule can define:

appearance chance;
replaced slot numbers, or every slot when left blank;
rarity weights;
group requirements;
duplicate protection.

The combined chance of all special rules in one product cannot exceed 100%.

Single-card projects

A Single Card project:

contains exactly one base card;
contains no booster products;
requires front and back art;
supports rarity, finish, value, effects, and corner radius;
appears as one standalone loose card in CardBay;
does not enter pack odds.

Room-theme projects

A Room Theme can provide:

main-room background;
Stream-room background;
background music;
project name, ID, author, version, and description.

At least one background or music file is required. Room themes do not add cards, rarities, or packs.

Recommended room images are 1920 x 1080. Current music import supports MP3, WAV, OGG, and WebM.

CardBay Item projects

An Item project creates a standalone room prop rather than a card or sealed product. Players with the project installed can buy copies from the Items category in CardBay, arrange them in the Main Room, select owned copies for the Stream Room through WhatchaGot, and sell them back through CardBay.

An Item project can define:

player-facing title, creator, version, description, and price;
a storefront and project thumbnail;
either a normal 2D image prop or a binary GLB model;
separate default position, size, and rotation for the Main Room and Stream Room;
GLB pitch and a per-room creator lock that prevents player repositioning;
a portable .ripset backup and Steam Workshop release like the other Creator Studio project types.

Make an image item

From the title screen, open Creator Studio.
Open My Projects and choose Item.
Enter the title, price, creator, version, and description.
Choose Item image and select a supported image. Transparent PNG artwork usually works best for a cut-out prop.
Enter each temporary room preview to set the Main Room and Stream Room defaults.
Save the project, then return to My Projects to create a backup or publish it.
In a game save, open CardBay, choose Items, and buy a copy to test it.

For an image prop, drag it in Creator Studio to set its default position. The wheel rotates it, and Shift + wheel resizes it. In the game, hover the purchased item and use the on-screen controls to move, rotate, or resize that copy.

Make a GLB item

Choose 3D model in the same Item editor and select a binary .glb file.

The file must use the .glb binary container, not a separate .gltf file.
Textures must be embedded inside the GLB. External texture or .bin files are not packaged beside it.
Creator Studio accepts a GLB up to 100 MB. Use a much smaller optimized model when possible and always prove portability by exporting and reimporting the finished .ripset.
Creator Studio renders a transparent thumbnail automatically. You can replace the thumbnail image to choose a different CardBay storefront view without replacing the model.
The temporary room preview supports left-drag orbit, right-drag position, wheel zoom, yaw, pitch, and a perspective guide for matching the current room background.
Lock Model in This Room preserves the creator's default transform for that room. Leave it unlocked when players should be able to adjust their own copy.

In the game, an unlocked GLB uses left drag to orbit, right drag to move, and the wheel to zoom. Each purchased copy keeps its own saved placement. The model is a visual room prop only: it cannot add scripts, click actions, menus, or gameplay logic.

Supported assets

Current .ripset packages support:

text

Images: PNG, JPG, JPEG, WebP, AVIF, GIF, BMP
Audio:  MP3, MPEG, WAV, OGG, WebM
Models: Binary GLB with embedded textures (Item projects only)

Creator Studio collects the project's assets into the exported .ripset so the installed project does not need to fetch them while playing.

Current package limits

Limit	Version 0.8.18 value
Schema version	1
Base cards before a performance warning	1,000
Hard maximum base cards	10,000
Maximum rarities	50
Slots/cards per pack before a performance warning	20
Hard maximum slots	50
Hard maximum cards per pack	50
Wrapper images per product	20
Products per project	50
Packaged assets	10,200
Audio file selected in Creator Studio	50 MB
GLB selected for an Item project	100 MB
Maximum package size	1 GB

These are 0.8.18 limits, not promises for every future version. Keep assets well below the maximums and test a clean export/import cycle; a file being accepted by the editor does not by itself prove that the complete project is practical to distribute or run.

Export and import

To share a Creator Studio project:

Fix every red validation issue.
Understand every warning.
Test the project's real player flow: open and simulate packs for a Card Set, buy the loose card for a Single Card, apply both rooms for a Room Theme, or buy and arrange the prop for an Item.
For a Card Set, simulate at least 100 packs and preferably 1,000.
Save until the top button reads green SAVED.
Use Save Backup or the export action to create a .ripset.
Import that file into a clean test project.
Restart Rip N Ship and test the installed project again.

The exported .ripset contains the project metadata and its packaged assets. Do not open it and rename or replace its internal files. Make changes in Creator Studio and export again.

Local Creator Studio storage

Creator Studio's active content is under:

text

Windows: %APPDATA%\rip-n-ship\CustomSets\
macOS:   ~/Library/Application Support/rip-n-ship/CustomSets/
Linux:   ~/.config/rip-n-ship/CustomSets/

The My Projects screen shows the installed Creator Studio projects.

Disabling or removing a card project prevents new purchases and openings from that source. Cards already owned by the player remain in the save. An owned Item also keeps its definition ID and placement data, but its art or model cannot render while the matching Item project is unavailable. Reinstalling the same stable project ID reconnects retained content on the next refresh.

Use the portable .ripset backup and keep source artwork outside the game's active storage folder.

Steam Workshop behavior

Steam Workshop can distribute both supported content systems.

Workshop ZIP mods

A Workshop ZIP-mod item places mod.json at the root of its Workshop content. The game installs or updates that managed copy during subscription refresh.

The Workshop publisher uses the manifest's:

name for the item title;
description for the item description;
icon for the preferred preview;
version for the update note.

New items begin as Private so the creator can check them before changing visibility in Steam.

Workshop `.ripset` projects

A Workshop Creator Studio item contains exactly one .ripset at its root. Use Publish to Steam or Update on Steam from the Creator Studio project dashboard.

The game protects manually imported content from being silently replaced by an unrelated Workshop item with the same ID. Resolve an ID conflict before expecting the subscription to activate.

See Publishing & Backups for the normal release workflow.

Not currently available to mods

Version 0.8.18 does not expose a supported way to:

replace the binder model or its table image;
replace official furniture, tables, or existing room props;
add a right-click action to an existing object;
add a generic website or live web tab;
create a URL-launcher mod;
add new menus, HUD panels, or arbitrary interface layouts;
inject JavaScript, HTML, or CSS;
load DLLs, native plugins, or executable scripts;
change game logic, progression, or save behavior;
change official card data or official pack odds;
add a texture or sound that no supported manifest field uses;
attach behavior, animation logic, or clickable actions to a Creator Studio Item;
create a complete arbitrary grading-service workflow.

The ZIP loader may display website as a fallback type when no type is supplied. That does not create generic website-mod support. There is no active url, website, or homepage manifest field in 0.8.18.

If a planned mod is on this list, it needs a future Mod API feature before a community package can implement it.

Troubleshooting

The ZIP has no `mod.json`

Place mod.json at the archive root or inside one immediate top-level folder.

The mod ID is invalid

Use 2 to 49 lowercase letters, numbers, or hyphens. Begin with a letter or number.

The mod is already installed

The local installer does not overwrite an existing mod directory. Uninstall the existing local copy before installing the update.

An arcade game is missing from the cabinet

Confirm:

top-level type is exactly arcade;
arcade.rom matches a real file inside the mod;
arcade.core exactly matches a supported core ID;
mod.json is valid JSON;
the game reloaded after installation.

The arcade game appears but does not start

Check the selected core, the actual file format, the expected ROM-set version, and any BIOS requirement. The mod loader confirms the file exists but cannot guarantee that a core can run it.

A Creator Studio Item is missing from CardBay

Confirm:

the project was saved or imported successfully;
the Item has a thumbnail image, or a GLB that generated one;
the project is active in My Projects;
CardBay is set to Buy > Items;
the game was restarted after installing or updating the project.

Buying an Item creates the room copy. Installing the project alone does not place a free copy into a save.

A GLB Item is blank or will not import

Confirm that the model is a binary .glb, all textures are embedded, and the file is no larger than Creator Studio's displayed limit. Replace the model in Creator Studio rather than adding loose texture or .bin files next to the .ripset. Before publishing, use Save Backup, import that backup on a clean test copy, buy the Item from CardBay, and verify it in the actual room.

A GLB Item cannot be moved in a room

The creator can lock a GLB separately in the Main Room and Stream Room. If the model was intentionally published as locked, players cannot change that room's transform. If you are the creator and want it adjustable, open the Item project, enter that room preview, unlock the model, increase the project version, and publish the update.

A Workshop subscription is missing

Wait for Steam to finish downloading it.
Use Refresh Subscriptions.
Restart the game once.
Check for a local mod or project using the same ID.
Confirm the item was built for the current Rip N Ship version.

Version 0.8.18 release checklist

Before sharing any mod:

Confirm the package uses the correct ZIP or .ripset format.
Keep all released IDs stable.
Increase the package version for an update.
Install the exported package from a clean copy.
Restart the game and test it again.
Test the actual feature, not only whether Workshop lists it.
For an Item, buy it from CardBay, test its room controls, and test a clean .ripset export/import.
State that the mod was tested with Rip N Ship 0.8.18.
Check this Mod API page again whenever Rip N Ship updates.

Check for a newer API guide

This reference is intentionally tied to game version 0.8.18. Future game updates may change IDs, limits, fields, loaders, or supported features and may break older mods. Always use the newest Mod API documentation available for the game version you are targeting.

Mod API ​

Choose the correct format ​

Mod API compatibility ​

ZIP mods ​

Folder layout ​

Base manifest ​

ZIP mod IDs ​

Static assets ​

Install a local ZIP ​

Arcade mods ​

Complete example ​

Arcade fields ​

Supported cores ​

BIOS folder ​

Test an arcade mod ​

Grading-provider assets ​

Recognized fields ​

Current limits ​

Creator Studio .ripset mods ​

Content types ​

What a card-set project can change ​

Stable IDs ​

Card image naming ​

Card and printing behavior ​

Foil and material effects ​

Pack slots ​

Special-pack rules ​

Single-card projects ​

Room-theme projects ​

CardBay Item projects ​

Make an image item ​

Make a GLB item ​

Supported assets ​

Current package limits ​

Export and import ​

Local Creator Studio storage ​

Steam Workshop behavior ​

Workshop ZIP mods ​

Workshop .ripset projects ​

Not currently available to mods ​

Troubleshooting ​

The ZIP has no mod.json ​

The mod ID is invalid ​

The mod is already installed ​

An arcade game is missing from the cabinet ​

The arcade game appears but does not start ​

A Creator Studio Item is missing from CardBay ​

A GLB Item is blank or will not import ​

A GLB Item cannot be moved in a room ​

A Workshop subscription is missing ​

Version 0.8.18 release checklist ​

Mod API

Choose the correct format

Mod API compatibility

ZIP mods

Folder layout

Base manifest

ZIP mod IDs

Static assets

Install a local ZIP

Arcade mods

Complete example

Arcade fields

Supported cores

BIOS folder

Test an arcade mod

Grading-provider assets

Recognized fields

Current limits

Creator Studio `.ripset` mods

Content types

What a card-set project can change

Stable IDs

Card image naming

Card and printing behavior

Foil and material effects

Pack slots

Special-pack rules

Single-card projects

Room-theme projects

CardBay Item projects

Make an image item

Make a GLB item

Supported assets

Current package limits

Export and import

Local Creator Studio storage

Steam Workshop behavior

Workshop ZIP mods

Workshop `.ripset` projects

Not currently available to mods

Troubleshooting

The ZIP has no `mod.json`

The mod ID is invalid

The mod is already installed

An arcade game is missing from the cabinet

The arcade game appears but does not start

A Creator Studio Item is missing from CardBay

A GLB Item is blank or will not import

A GLB Item cannot be moved in a room

A Workshop subscription is missing

Version 0.8.18 release checklist