Item Development Guidelines

This guide provides structured instructions for creating and managing custom items in DSPACE. Well-designed items enhance the game experience and expand the capabilities of processes and quests.

Item Philosophy

DSPACE items should:

Serve a purpose - Connect to processes, quests, or educational concepts
Be realistic - Represent objects that could exist in a space exploration context
Have clear relationships - Establish connections to other game elements
Follow naming conventions - Use consistent, descriptive terminology
Include educational value - Teach concepts relevant to space exploration

Item Categories

When creating items, consider these categories:

Core Item Types

Resources: Basic materials like energy units (dWatt), currency (dUSD), raw materials
Tools & Equipment: Devices used to perform processes (3D printers, sensors, etc.)
Components: Parts used in constructing larger systems (rocket parts, circuit boards)
Consumables: Items that get used up through processes (fuel, nutrients, filament)
Educational: Items that provide information or learning opportunities

Item Structure Guidelines

Basic Properties

Every item requires the following basic properties:

name: Descriptive name of the item (required)
description: Detailed explanation of the item's purpose and use (required)
- image: Visual representation of the item (required)
price: Value in game currency (optional). Enter a positive amount and select the currency; the form stores the combined string (e.g., 25 dUSD).
priceExemptionReason: Required when an item has no price. Use this for non-shop items such as COMPONENT, SOULBOUND, or TROPHY.
- Important: Omitting price does not mean an item should be auto-buyable. In process UIs, non-priced items are intentionally skipped by Buy required items, so keep process-only gates process-crafted.
unit: Measurement unit for the item (e.g., kg, L, watts) (optional)
type: Classification or category (optional)

Implementation State

Currently, the ItemForm.svelte component supports creating and editing items with the properties listed above. It uploads images, persists data to IndexedDB, and now includes a dependency editor so complex items can declare required ingredients without editing JSON manually.

List any prerequisite item IDs in the Dependencies field using commas or new lines. The form trims whitespace, ignores blank rows, and the live preview immediately reflects the dependency list so you can verify relationships before saving.

As you fill out the form, an ItemPreview component displays a live preview so you can confirm the details before submitting. The layout automatically adjusts on small screens so form fields expand to the full width for easier touch input, and action buttons stack vertically on narrow displays. You can safely experiment with different values before saving-no data is written until you click Create Item.

The form provides inline validation messages if you attempt to submit without a name, description, or image, helping ensure items meet basic requirements before saving. Automated Playwright tests verify that the preview appears when entering text and that uploaded images render correctly. This ensures cross-browser compatibility of the custom item workflow.

All items must now conform to the JSON schema located at frontend/src/pages/inventory/jsonSchemas/item.json. Run the itemValidation test to ensure any additions meet the schema requirements.

Item Best Practices

Naming Conventions

Be specific - "Solar Panel (5W)" is better than "Solar Panel"
Include measurements - Add units when relevant (e.g., "Water Tank (10L)")
Use standard terminology - Research proper terms for scientific concepts

Descriptions

Explain purpose - What the item is used for
Include educational content - Brief facts about real-world equivalents
Connect to space context - How the item relates to space exploration
Keep it concise - 1-3 sentences is usually sufficient

Images

When you upload a custom item image in-game, the client downsamples it to a 512×512 JPEG and compresses it to target < 50KB. This keeps IndexedDB storage small, speeds up backups, and improves load times. Developers should reuse the shared helper at frontend/src/utils/imageDownsample.js for any future custom image ingestion points.

Clear representation - Should clearly show what the item is
Consistent style - Match the visual style of existing items
Appropriate format - Use PNG or JPG format, sized appropriately
Attribution - Include credits for images if required

Item Relationships

Items in DSPACE are often connected to other game elements:

Process Relationships

Required by: Processes that need this item to run but don't consume it
Consumed by: Processes that use up this item
Created by: Processes that produce this item

Quest Relationships

Required for: Quest dialogue options that need this item
Granted by: Quests that give this item as a reward or during dialogue

When creating custom items, consider how they might connect to:

Existing processes
Existing quests
New processes you're developing
New quests you're developing

Examples

Resource Example

{
    "name": "Recycled Aluminum (100g)",
    "description": "Lightweight aluminum recovered from waste materials. Used in manufacturing various components for space habitats.",
    "image": "/assets/recycled-aluminum.jpg",
    "price": "15",
    "unit": "100g",
    "type": "resource"
}

Tool Example

{
    "name": "Multimeter",
    "description": "A device for measuring electrical voltage, current, and resistance. Essential for testing and troubleshooting electronic circuits.",
    "image": "/assets/launch_controller.jpg",
    "price": "250",
    "unit": "unit",
    "type": "tool"
}

Component Example

{
    "name": "Solar Cell Junction Box",
    "description": "A protective enclosure for solar panel electrical connections. Shields connections from moisture and environmental damage.",
    "image": "/assets/junction-box.jpg",
    "price": "45",
    "unit": "unit",
    "type": "component"
}

Contribution Workflow

The recommended way to contribute items is through the custom content bundle workflow, which keeps related quests, items, and processes together:

Create item through the in-game interface at /inventory/create
Export your created item as JSON from the management page:
- After saving your item, navigate to /inventory/manage
- Locate your newly created item in the list and use the export functionality to download the JSON
- Save the exported JSON file - this will be included in your content bundle
Create any related processes at /processes/create and export them similarly
Create any related quests at /quests/create and export them similarly
Package everything into a bundle JSON (see Custom Content Bundles)
Submit the bundle for review at /bundles/submit
Respond to feedback on the generated pull request
Once approved, your content bundle becomes available to all players

Alternatively, you can follow the traditional manual workflow:

Develop your custom item(s) following these guidelines
Test the item(s) in various processes to ensure they function as expected
Create a content bundle JSON with related quests and processes
Submit a pull request with your bundle file in submissions/bundles/
Respond to feedback during code review
Once approved, your content will be merged into the official game

Areas Needing More Content

We're particularly interested in new items that cover:

Sustainable materials and recycling
Energy storage and generation
Life support systems
Scientific instruments
Plant cultivation tools
Water management systems
Educational models and demonstrations

By following these guidelines, you'll create items that enhance gameplay while advancing DSPACE's mission of democratizing space exploration through education.