README.md

metadata

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

npm install
npm run build   # build the client into dist/client
npm run dev     # run the server on :7860 in open dev mode