PaperclipWorld

• 中文说明 / README_cn.md

PaperclipWorld is a 2D pixel-game-style control interface for Paperclip.

It turns Paperclip's generated assets, runtime activity, and assets related working state into a visual library interface that can be browsed, previewed, and monitored in real time.

Overall, it aims to feel more like a living pixel archive than a plain folder tree.

Highlights

• classify, index, and manage many different asset types produced by Paperclip
• open and preview those assets directly inside the interface
• see what Paperclip is currently accessing, using, or processing
• connect runtime behavior to concrete asset rooms instead of raw folders
• present the whole workflow in a more approachable 2D pixel-game UI
• keep the art layer replaceable so visuals can evolve independently from the logic layer

What It Does

PaperclipWorld maps Paperclip-related resources into visual rooms such as:

• document archive
• image atelier
• memory vault
• skill forge
• interface gateway
• code lab
• scheduler
• alarm board
• runtime monitor
• queue hub
• break room

The interface is mainly designed to answer two questions:

1. What assets already exist?
2. What is Paperclip doing with them right now?

Core Features

• room routing driven by live Paperclip activity
• asset partitions aligned to Paperclip resource types
• direct in-panel asset browsing and preview
• actor movement linked to room state
• debug overlays for mapping and route inspection
• replaceable pixel-art scene assets

Installation

Easiest Setup: Send the Repo to Paperclip

If the other person already has Paperclip installed, the easiest path is to send the repository URL to their Paperclip and let it install and launch the project automatically.

You can send a prompt like this:

Please install and launch this repository: clone https://github.com/paperclipai/paperclip, enter the paperclip-world folder, run npm install, npm run validate, then start the dev server and tell me the final URL.

If you need LAN access, add a note asking Paperclip to enable LAN access and report the LAN URL.

Standard Local Setup

cd paperclip-world
npm install
npm run validate
npm run dev

Then open:

• local only: http://127.0.0.1:5173/
• LAN mode if enabled: http://<your-ip>:5173/

If your Paperclip installation is not under the default path, the recommended way is to edit:

• paperclipworld.config.json

If you prefer environment-variable overrides, copy and fill:

cp .env.example .env

and set:

• PAPERCLIP_HOME
• PAPERCLIP_WORKSPACE

Development Commands

npm run dev
npm run validate
npm run typecheck
npm run build

Optional QA commands:

npm run qa:movement
npm run qa:visual:baseline
npm run qa:visual

These QA commands generate local temporary artifacts. They currently write into tmp/qa/ and are not meant to be part of the public repository.

Runtime Model

PaperclipWorld is driven by protocol-style data plus live telemetry:

• src/data/map.logic.json — room layout, anchors, walk graph, work zones
• src/data/asset.manifest.json — logical asset definitions
• src/data/scene-art.manifest.json — actor and scene art bindings
• src/data/work-output.protocol.json — work-state mapping and output semantics
• scripts/paperclip-telemetry.mjs — bridge from Paperclip state into live museum signals

Configuration

PaperclipWorld uses paperclipworld.config.json at the repository root as the public-facing config entry point.

Current config surface includes:

• debug — whether to show room anchors, route circles, and other debug overlays
• host — 127.0.0.1 for local-only access, 0.0.0.0 for LAN access
• port — dev server port
• locale — en or zh
• defaultActorVariant — choose the default actor skin

Default config file:

{
  "paperclip": {
    "home": "",
    "workspace": ""
  },
  "server": {
    "host": "127.0.0.1",
    "port": 5173
  },
  "ui": {
    "defaultLocale": "en",
    "showDebugToggle": false,
    "defaultDebugVisible": false,
    "showInfoToggle": true,
    "defaultInfoPanelVisible": true,
    "showThemeToggle": false
  },
  "actor": {
    "defaultVariantId": "capy-claw-emoji"
  },
  "telemetry": {
    "pollMs": 2500
  }
}

Supporting files:

• .env.example — optional environment-variable override example
• scripts/paperclipworld-config.mjs — shared config loader for config file + env overrides

Paperclip Path Discovery

PaperclipWorld does not hardcode a single machine path.

Current lookup strategy:

• read paperclipworld.config.json first
• override with PAPERCLIP_HOME if provided
• override with PAPERCLIP_WORKSPACE if provided
• if neither config nor env is set, fall back to the standard Paperclip layout:
  • ~/.paperclip
  • ~/.paperclip/workspace

That means:

• standard Paperclip installations should work out of the box
• custom installations can be supported through config or environment-variable overrides

Open-Source Repository Guidance

A public release should mainly keep:

• runtime code
• required public assets
• installation commands
• configuration docs
• a few polished preview assets

Internal QA captures, prompt drafts, and iteration logs are usually better removed from the public release.

License

Code is licensed under MIT:

• /LICENSE

Assets are licensed under CC BY-NC-SA 4.0:

• /LICENSE-ASSETS.md
• Non-commercial sharing, adaptation, and redistribution are allowed with attribution.
• If you redistribute adapted assets, you must keep them under the same license.
• For commercial use of this project, replace the included art assets with your own, or obtain separate permission.

Acknowledgements

• This project is inspired by Star-Office-UI.
• Special thanks to @simonxxooxxoo and @ringhyacinth.