Sproutly-Bot

Sproutly-Bot is a cozy plant-care game for Discord communities. Players grow a plant, manage its health and hydration, earn coins, collect achievements, and compete on a server leaderboard. Live weather from Tampere, Finland adds changing bonuses and hazards to the greenhouse.

Built with Node.js, CommonJS, and discord.js v14.

Features

• Plant growth with six stages, species traits, rarity, and care-based selling bonuses
• Daily rewards, experience, levels, achievements, and server leaderboards
• A seasonal shop with seeds, fertilizers, consumables, and protection items
• Weather effects that refresh automatically every hour
• Persistent JSON storage with atomic saves and a recovery backup
• Slash commands that require no privileged Message Content Intent

Quick Start

Requirements

• Node.js 18 or newer
• A Discord application and bot token

Install and configure

npm install
Copy-Item .env.example .env

Open .env and set the required token:

DISCORD_TOKEN=your_bot_token_here

Then start the bot:

npm start

For local development with automatic restarts:

npm run dev

Run the test suite with:

npm test

Tests use temporary data files and do not modify the live data/plants.json file.

Configuration

Variable	Required	Description
DISCORD_TOKEN	Yes	Discord bot token. Keep this secret.
DISCORD_GUILD_ID	No	Registers commands in one server for faster development updates. Omit it to register global commands.
PLANT_DATA_PATH	No	Path to the persistent plant data file. Defaults to data/plants.json.

The included .env.example contains all supported variables.

Discord Setup

Invite the application with these OAuth2 scopes:

• bot
• applications.commands

The bot needs only these permissions in the channels where it operates:

• View Channel
• Send Messages

Sproutly-Bot uses only the Guilds Gateway Intent. It does not need Message Content Intent or any other privileged intent. Weather changes and freezing alerts are sent to the server system channel when available, or the first text channel where the bot can send messages.

All commands are slash commands and must be used inside a server.

Commands

Progress and community

Command	Purpose
/commands	List available commands
/info	View items, weather effects, and seasonal information
/inventory	View coins, seeds, fertilizers, and items
/daily	Claim daily coins and build a streak
/profile	View your player profile
/stats	View your plant stats
/stats user:<member>	View another member’s plant stats
/badges	View your achievements and badges
/badges user:<member>	View another member’s achievements
/leaderboard sort:<level\|coins\|rareblooms\|achievements>	View the server leaderboard by category
/reset confirm:Confirm	Permanently reset your account

Plants and care

Command	Purpose
/plant	List your owned seeds
/plant species:<species>	Plant a seed in the shared greenhouse
/name plant_name:<new name>	Rename your plant
/garden	View plants in the shared greenhouse
/water	Water your plant; one-hour cooldown
/sunlight	Give your plant its daily sunlight
/fertilize type:<basic\|premium>	Apply fertilizer
/use item:<item>	Use an item from your inventory
/nutrient	Use a Nutrient Pack for up to 20 health
/heatlamp	Protect your plant from Snowy weather for 24 hours
/weather	Check and refresh current Tampere weather

Shop and economy

Command	Purpose
/shop show catalog	View the shop catalog
/shop action buy_item item:<item>	Buy fertilizer or another shop item
/shop action buy_seed seed:<species>	Buy a seed
/sell	Sell your plant based on stage, rarity, and care

Available species are fern, cactus, orchid, rose, tulip, lavender, pine, sunflower, bamboo, bonsai, and moonflower.

Gameplay

Plants advance one stage every 30 minutes. The stages are Seed, Sprout, Seedling, Young plant, Mature plant, and Rare bloom. Hydration decreases by 20 points every 24 hours without watering, and health is capped between 0 and 100.

Rarity bonuses are Common (+0), Rare (+25), Exotic (+50), and Seasonal (+75) coins when selling. High health and care can add further selling bonuses. Weather can improve growth and hydration, while Snowy weather causes 8 health damage per hour unless a Heatlamp is active.

Deployment

Sproutly-Bot runs as a worker and does not need an HTTP port. Any Node.js host that runs npm start can host it. For Railway:

1. Create a service from this repository.
2. Set DISCORD_TOKEN in the service variables.
3. Add a Volume mounted at /data for persistent player data.
4. Set PLANT_DATA_PATH=/data/plants.json.

Without persistent storage, the bot runs normally but local game data may be lost when the service is recreated. The store writes a .bak recovery file after successful saves.

Project Structure

commands/       Discord slash command modules
lib/            Persistence and plant-game logic
data/           Local plant data (not committed)
tests/          Node.js test suite
index.js        Bot startup, command registration, and weather scheduler

To add a command, create a module in commands/ that exports a lowercase name, a description, and an asynchronous execute function. index.js discovers command modules automatically and registers them with Discord.

Policies

• Terms of Service
• Privacy Policy

License

This project is distributed under the ISC license.