Build your own cozy packing game.

01 · Overview

What this asset gives you

CozyCrate is a complete, data-driven 2D packing-sim foundation. Runtime rules live in plain C# services; content and tuning live in ScriptableObjects; the presentation is assembled by event-driven uGUI views.

02 · First run

Quick start

1. Open the project in Unity 6000.0.62f1. Using the exact editor patch is recommended. The project uses URP 17.0.4 and the Unity Input System 1.11.2.
2. Use the Welcome to CozyCrate window. It opens automatically on the project's first Editor session and links directly to the Boot scene, documentation, Content Wizard, validation, and any missing setup. Choose Close for now to hide it for the session or Don't show again to disable startup display for this project.
3. Let Unity import packages and assets. If TextMesh Pro prompts for resources, import the essentials or use CozyCrate > Import TMP Essentials.
4. Open Assets/CozyCrate/Scenes/Boot.unity. Boot is the composition root and should be the first scene in Build Settings.
5. Press Play. Boot loads the catalog, settings, save, audio service, and Main Menu. Starting or continuing a run opens Workshop.
6. Validate before modifying. Run CozyCrate > Validate Content. A clean starter package reports zero problems.

03 · Technical map

Architecture and runtime flow

Three deliberately small scenes host a runtime-built application. A single service graph owns game state, while views react through an EventBus.

Assembly direction

CozyCrate.App          Composition: Bootstrapper, AppFlow, GameSession
  CozyCrate.UI         Runtime uGUI views, HUD, tablet, tutorials
  CozyCrate.Progression  Shift lifecycle, reputation, upgrades
  CozyCrate.Economy      Payouts, money, bank, loans, bills
  CozyCrate.Systems      Suspicious-order consequences, optional cat service
  CozyCrate.Audio        Audio routing and procedural fallback
  CozyCrate.Gameplay     Orders, packing, validation, item processes
  CozyCrate.Data         ScriptableObject schemas and ContentCatalog
  CozyCrate.Core         Events, service access, saves, settings, utilities

The gameplay loop

Read order slip -> arrange intake -> process dirty/broken items -> choose a box
-> place items -> apply protection -> attach handling/address labels -> seal
-> drag parcel to conveyor -> validate -> payout -> finish quota -> daily report
-> tablet: restock / shop / clients / bank / settings -> next day

The ShippingValidator is the final authority. Missing box, items, address, or seal cause a hard reject. Lesser mistakes produce payout penalties and report feedback.

04 · Project map

Where everything lives

Assets/CozyCrate/
|-- ArtSources/               Curated editable source textures
|-- Data/                     ScriptableObject content and configuration
|   |-- Boxes/ Clients/ Consumables/ Items/ Stickers/ Upgrades/
|   |-- Config/               GameConfig, UITheme, difficulty profiles
|   |-- Localization/         String-table overrides
|   `-- Shapes/               Item footprint definitions
|-- Documentation/            Single customer guide and licensing reference
|-- Editor/DataTools/          Wizards, generators, validator, build menu
|-- Resources/CozyCrate/       Catalog, art, audio-library asset
|-- Scenes/                    Boot, MainMenu, Workshop
|-- Scripts/                   App, Audio, Core, Data, Economy, Gameplay...
|-- Tests/                     EditMode and PlayMode suites
`-- Third Party Notices.txt    AI-assisted content and included-content notices

Packages/manifest.json         Unity package versions
ProjectSettings/               Rendering, input, player/build settings

05 · Data-driven content

The content model

Definitions are assets; runtime objects refer back to them. Stable lowercase IDs are used in saves, prerequisites, inventory, and lookups.

ID rules

• Use unique, lowercase, stable identifiers such as item_tea_kettle.
• Do not change an ID after publishing a build unless you also migrate existing saves.
• Asset filenames may change; runtime identity comes from the definition's id.
• Run CozyCrate > Validate Content after additions or dependency changes.

06 · Content recipe

Create items and footprint shapes

Recommended: Content Wizard

1. Open CozyCrate > Content Wizard and select Item.
2. Set display name, category, footprint, weight, base value, and rotation.
3. Enable the requirements the shipping validator must enforce: fragile, hazard, keep dry, or orientation-sensitive.
4. Set dirty/broken arrival probabilities if the item should use a processing mini-game.
5. Assign a sprite now or leave it empty for a fallback, then click Create Item. The wizard creates, registers, saves, and validates it.

How an item enters generated orders

An item becomes eligible when it is registered in the catalog and at least one unlocked client includes its ItemCategory. Later procedural days sample that client-filtered pool.

Visual size versus logical footprint

Manual creation

Duplicate a nearby item asset, give it a new ID, adjust its fields, and add it to Catalog.asset > items. Manual creation is useful for copying a carefully tuned family of items.

07 · Level design

Create and tune days

Days 1-8: authored curriculum

Modify or add an authored introduction day

1. Add or update the unlock constant in Scripts/Gameplay/FeatureUnlocks.cs.
2. Add a matching case in OrderGenerator.GenerateTutorialDay(). Use existing registered item IDs and ensure each order fits a box.
3. Update TutorialDirector so help appears when the new action is actually relevant.
4. Make the tray tool obey the same unlock day, following TrayView.AddLock().
5. Move the procedural-day boundary in OrderGenerator.GenerateDay() if the curriculum becomes longer than day 8.
6. Add assertions to OrderGeneratorTests and a PlayMode flow test.

Day 9 onward: seeded procedural progression

Procedural days use the run seed, current day, unlocked clients, and these GameConfig.asset curves:

Make the campaign longer, faster, or harder

Edit the curve keys in GameConfig.asset. Curves clamp outside their authored range, so add later keys if you want difficulty to keep changing after the current final key. Re-run balance and order-generation tests afterward.

08 · Brands and progression

Create a client

1. Open CozyCrate > Content Wizard > Client.
2. Choose one or more item categories. Those categories form the client's procedural item pool.
3. Set the value multiplier, unlock reputation, optional unlock price, item-count range, and special-handling bias.
4. Add an original name, color, blurb, and logo art, then create the asset.

startsUnlocked clients are always restored as available, including on fresh saves. Other clients reveal when total reputation reaches their threshold. Free clients unlock immediately; priced clients can then be purchased in the tablet's Clients app.

09 · Packing model

Boxes, placement, and shipping validation

The player experiences loose, direct placement. Underneath, logical footprints and alpha-aware silhouettes keep items in bounds and prevent invalid overlap.

Add or modify a box

1. Duplicate the closest BoxDefinition in Data/Boxes.
2. Give it a unique ID and an unused or intentionally shared BoxSize strategy.
3. Set logical dimensions, cost, initial stock, capacity, and correctly framed open/closed sprites.
4. Register it in Catalog.asset > boxes, ordered from smallest to largest if size-based selection should remain intuitive.
5. Test the new capacity with BoxFitter, placement, seal/unseal, drag-to-conveyor, and shipping.

Protection and correctness

• Packing peanuts are required for every shipped carton and count as a consumable.
• Fragile items require bubble protection and the fragile handling label.
• The correct address is a hard requirement; an incorrect code returns the parcel.
• A parcel must contain all required items and be sealed before it can ship.
• Oversized boxes and incomplete void filling can reduce payout.

10 · Tools and labels

Handling tools, stickers, and consumables

Requirements derive from the order type and item flags. A sticker is a freely positioned visual mark on the carton, while validation records its semantic type.

Add a new handling type

1. Append a new value to StickerType. Avoid reordering serialized enum values.
2. Create and register a matching StickerDefinition plus its sheet ConsumableDefinition.
3. Derive the requirement from an item/order property in Order.RequiredStickers().
4. Add its unlock day in FeatureUnlocks and tutorial behavior in TutorialDirector.
5. Add any penalty field to GameConfig and validate it in ShippingValidator.
6. Test the correct, missing, and wrong-label cases.

11 · Purchasables

Create upgrades and effects

Use an existing effect type

1. Open CozyCrate > Content Wizard > Upgrade.
2. Set name, kind, price, description, effect type/value, and optional prerequisite.
3. Create the asset. It is registered and validated automatically.
4. Play through the real tablet Shop app and verify purchase, live effect, affordability state, and save/reload.

Add a brand-new effect

Append an EffectType value and implement its aggregation in ProgressionService.RecomputeEffects(). That method is the intended seam between purchased definitions and live systems. Persist only the purchased upgrade ID; aggregates are rebuilt after load.

12 · Presentation

Retheme the UI, replace art, and add audio

Global visual theme

Edit Assets/CozyCrate/Data/Config/UITheme.asset. It contains the shared palette and category colors read by UIFactory and placeholder rendering. Runtime UI is composed in Scripts/UI; change layout there or replace individual builders with prefabs while keeping the same service/event contract.

Sprite workflow

1. Place production art under Assets/CozyCrate/Resources/CozyCrate/Art/ in the appropriate subfolder.
2. Run CozyCrate > Prepare Generated Art. The importer configures Sprite/Single, transparency, no mipmaps, clamp, sRGB, 100 PPU, and suitable size/compression.
3. Assign the resulting sprite to the relevant Item, Box, Sticker, Client, Upgrade, or Consumable asset.
4. For general UI panels/buttons, preserve the intended 9-slice borders or configure equivalent borders in Sprite Editor.
5. Test at 16:9, a narrower aspect ratio, and each available UI scale setting.

Audio overrides

Add clips to Assets/CozyCrate/Resources/CozyCrate/AudioLibrary.asset. Each entry maps a string ID to an AudioClip. Common IDs include tape, coin, cat_meow, and music beds menu, work, and report. Missing entries fall back to procedural audio.

Settings separately control master, music, and SFX volume. Test override clips at every slider extreme and ensure loops do not click.

13 · Text

Localization and customer-facing strings

Strings_EN.asset is a key/value override table. Views request text through L.Get(key, English fallback). This makes it possible to replace wording without editing each view.

1. Search Scripts/UI for L.Get( to inventory existing keys.
2. Add or edit matching keys in Data/Localization/Strings_EN.asset.
3. For another language, create another StringTableSO and select it at boot before UI construction.
4. Replace the TMP font asset if the target language needs additional glyph coverage.
5. Test long strings at the largest UI scale, especially top bars, tray cards, order slips, tablet buttons, tutorials, and reports.

14 · Tuning

Economy, difficulty, and campaign balance

Per-order payout model

payout = round(baseReward x accuracy x boxEconomy x speed x suspiciousMultiplier)
         + rushBonus - boxCost - suppliesCost

Accuracy is reduced by the weighted infractions configured in GameConfig. Box economy rewards appropriately small cartons. Timed modes can award speed bonuses. The daily settlement then applies rent, utilities, bank interest, loan interest, pending fines, and upgrade modifiers.

Safe balancing loop

1. Duplicate the project or commit before broad tuning.
2. Adjust one family at a time: pacing, payout, penalties, or bills.
3. Run BalanceCurveTests to simulate a competent campaign.
4. Play representative early, middle, and late days on all three difficulties.
5. Verify bank, loan, client, restock, and upgrade affordability in the tablet.

15 · Persistence

Saves and settings

Both files are human-readable JSON under Application.persistentDataPath. On Windows with the shipped company/product identifiers, that normally resolves under:

%USERPROFILE%\AppData\LocalLow\Szekipapa77\CozyCrate\

Autosave behavior

• A day-start snapshot is written when a shift begins.
• Day completion stores the next morning's state.
• Quitting during work keeps the morning snapshot so the shift replays safely.
• Content references use stable IDs, not Unity object references.

Evolve the schema

Add fields with safe defaults, increment schemaVersion, and chain migration logic in SaveService.Migrate(). Test an old JSON fixture, a fresh save, and a current save. If you rename a content ID, migrate every saved list/key that can contain it.

16 · Workflow

Editor tools

17 · Quality assurance

Test before you publish

Open Window > General > Test Runner. Run both EditMode and PlayMode suites after functional changes.

Manual regression checklist

• Start a clean save in Chill, Normal, and Rush.
• Complete days 1-8 and confirm tools unlock only when introduced.
• Move items in intake; pack, rotate, reject overlap, and fill each carton size.
• Apply correct and incorrect addresses and each handling label.
• Seal, unseal, recycle, drag a completed parcel, and verify sorting order/tutorial overlays.
• Purchase every upgrade and priced client; restock every supply; deposit/withdraw/borrow/repay.
• Save, exit, relaunch, and verify balances, stock, progression, settings, and visuals.
• Check narrow, wide, and standard resolutions plus every UI-scale setting.

Development playtest bot

Build with the development command, then launch CozyCrate.exe -playtest. The bot operates the real UI and writes screenshots and a PASS/FAIL log beneath Application.persistentDataPath/playtest/. Treat it as a smoke test, not a replacement for the full Test Runner or human UX review.

18 · Delivery

Build and export

Windows player

1. Run all content validation and tests; resolve Console errors.
2. Confirm Build Settings order: Boot, MainMenu, Workshop.
3. Review Company Name, Product Name, version, icons, default resolution, and URP quality.
4. Choose CozyCrate > Build Windows x64.
5. Run Builds/Windows/CozyCrate.exe on a clean machine/profile and test save creation.

Android landscape APK

1. Install Android Build Support, SDK/NDK Tools, and OpenJDK for Unity 6000.0.62f1.
2. Review Android icons, package identifier, minimum API level, and signing before a store release.
3. Choose CozyCrate > Build Android APK (Landscape).
4. Install Builds/Android/CozyCrate.apk on representative landscape phones and tablets and verify touch targets.

WebGL player

1. Install WebGL Build Support for Unity 6000.0.62f1.
2. Choose CozyCrate > Build WebGL.
3. Serve the complete Builds/WebGL directory over HTTP(S); opening index.html directly from disk is unsupported.
4. Verify loading, pointer input, audio activation, saving, fullscreen behavior, and responsive scaling in current desktop browsers.

Unity Asset Store package hygiene

• Include Assets/CozyCrate and avoid unrelated project content.
• Keep this Documentation folder inside the asset root so customers can reach it immediately.
• List Unity 6000.0.62f1 and URP 17.0.4 as the verified environment.
• Keep all required licensing and attribution information in the licensing section of this guide.
• Import the exported package into a blank compatible URP project and repeat Quick Start.

19 · Extension seams

Common code recipes

20 · Licensing & included content

What is included and where it came from

CozyCrate ships as an editable game template. This section summarizes licensing and attribution; the top-level Third Party Notices.txt provides the buyer-facing AI-assisted content disclosure and affected-content list.

Your responsibilities when extending the template

• Confirm commercial-use and redistribution rights for every art, audio, font, text, code, or brand you add.
• Keep attribution and license material supplied with third-party content you import.
• Do not ship added content when its commercial-use or redistribution rights are unclear.
• Review target-platform and Unity-package terms before publishing your modified game.

21 · Help

Troubleshooting