| --- |
| title: WEED-SIM |
| colorFrom: green |
| colorTo: indigo |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # WEED-SIM — Maryjane Genetics Sim (Telegram Mini App) |
|
|
| A fictional plant-genetics breeding game, played inside Telegram. Players grow |
| pixel-art strains, breed parent plants, clone promising specimens, chase |
| leaderboard records, and barter in-game clone lots through a fictional exchange. |
|
|
| The game is about collectible genetics, color expression, lineage strategy, and |
| community competition. It does not provide real-world cultivation instructions, |
| does not sell or facilitate sale of real products, and does not support trading |
| in-game goods for real money. Free players get a lifetime allowance of free |
| crosses, full leaderboards, and read access to the exchange; the one-time |
| Breeder's Pass (Telegram Stars) unlocks unlimited breeding, cloning, trading, |
| and Agent Control. Everything inside the game is barter-only fiction. |
|
|
| ## Gameplay |
|
|
| - Grow starter plants from seedling to mature stages. |
| - Select two plants on deck and predict the cross before breeding. |
| - Breed offspring with inherited potency, yield, grow time, stability, color, bloom pattern, and lineage data. |
| - Clone valuable plants to preserve genetics and create tradeable in-game clone lots. |
| - Compete on shared leaderboards for THC, CBD, yield, grow time, stability, generation, vibrance, and rarity. |
| - Browse the clone exchange for fictional listings, requests, offers, and leaderboard-backed valuations. |
| - Use the Speciation Bench, Deck, Market, Observer Bus, and FX views to inspect the evolving population. |
|
|
| ## Fictional Genetics Model |
|
|
| Each plant has allele pairs for numeric traits and color traits. Stability |
| affects how strongly inherited traits express and how wild a cross can become. |
| Numeric traits such as THC, CBD, yield, and grow time are gameplay stats only. |
| Bud and leaf visuals are rendered from sprite masks, palettes, bloom patterns, |
| and inherited color genes. |
|
|
| ## Agent Control |
|
|
| The game includes an optional Agent Control panel. When a player chooses to |
| create a session, the game generates a scoped, expiring token and a paste-ready |
| handoff packet for any compatible agent or automation client: |
|
|
| - The in-game agent HUD drives the sim through `POST /api/agent-link/call`. |
| - External agents connect through the MCP JSON-RPC endpoint `POST /external/mcp` |
| with the `X-Agent-Link-Token` header. First call: the `agent_bootstrap` tool. |
|
|
| No LLM provider is embedded in the game. Agent Control is optional, |
| provider-neutral, and player initiated; agents bring their own model. |
|
|
| ## Data Stored |
|
|
| Game state is stored as JSON under `WEEDSIM_DATA_DIR` (an HF Storage Bucket |
| mount in production). Stored data can include: |
|
|
| - Telegram numeric user id and a persisted display name derived from it. |
| - Player inventory, plant records, stages, lineage, clone attempts, and selected on-deck plants. |
| - Shared leaderboard entries; fictional market listings, offers, requests, and clone-lot state. |
| - Observer-bus receipts, Agent Control sessions, and event records. |
| - Breeder's Pass entitlements (Telegram payment charge id, Stars amount). |
|
|
| The app does not ask players for passwords, card details, real names, address |
| information, or external account credentials. Payments happen entirely inside |
| Telegram's Stars flow. |
|
|
| ## Safety Boundaries |
|
|
| - All genetics, clone lots, potency values, and market values are fictional game mechanics. |
| - No real-world plant material, controlled substance, medicine, or product can be bought, sold, shipped, or exchanged through the app. |
| - The in-game marketplace is barter-only: no currency, no cryptocurrency, no cash-out path. |
| - The app should not be used for real-world cultivation, medical, legal, or commercial advice. |
|
|
| ## Architecture |
|
|
| - **Client**: React + Vite static build, run as a Telegram Mini App |
| (`splash.html` gates entry via the Breeder's Pass, `game.html` is the sim). |
| - **Server**: Hono on Node 22 (`src/server`), port 7860. Telegram WebApp |
| `initData` is HMAC-verified per request; identity is the stable Telegram user id. |
| - **Persistence**: JSON files under `WEEDSIM_DATA_DIR`. In production, mount an |
| HF Storage Bucket at `/home/user/app/data` (or point `WEEDSIM_DATA_DIR` at |
| your mount path) so state survives Space restarts. |
|
|
| ## Space configuration |
|
|
| Secrets: |
|
|
| - `BOT_TOKEN` — the Telegram bot token. Without it the server runs in open dev |
| mode: anonymous identity, no payments, no pass gate (local development only). |
|
|
| Variables: |
|
|
| - `WEBAPP_URL` — public URL of this Space (e.g. `https://tostido-weed-sim.hf.space`). |
| When set, the server self-configures the Telegram payment webhook at boot. |
| - `PASS_PRICE_STARS` — Breeder's Pass price in Telegram Stars (default 420). |
| - `FREE_BREED_LIMIT` — lifetime free crosses for players without a pass (default 25). |
| - `PASS_FREE_USER_IDS` — comma-separated Telegram user ids that enter without |
| buying (operator and testers). |
| - `WEEDSIM_WORLD_ID` — shared world identifier (default `world-1`). |
|
|
| ## Local development |
|
|
| ```bash |
| npm install |
| npm run build # build the client into dist/client |
| npm run dev # run the server on :7860 in open dev mode |
| ``` |
|
|
