Skip to content

README.md

Latest commit

 

History

History
145 lines (125 loc) · 4.83 KB

README.md

File metadata and controls

145 lines (125 loc) · 4.83 KB
Raw

TerraDiscord

TerraDiscord is a Infrastructure-as-Code tool that allows you to manage your server structure through JSON files. You can define roles, categories, channels, and permissions in a single configuration file and apply it to any server where the bot has administrator privileges.

Core Features

  • Manage server name and description via JSON.
  • Automated creation of roles with specific colors and permissions.
  • Category and channel management (Text, Voice, News, Forum, Stage).
  • Permission overrides for specific roles on a per-channel basis.
  • Export your current server structure back to JSON.

Setup

  1. Install dependencies: 
    pip install -r requirements.txt
  2. Create a .env file in the root directory: 
    DISCORD_TOKEN=your_bot_token_here
  3. Run the bot: 
    python main.py

Folder Structure

  • presets/: Place your custom JSON configurations here.
  • examples/: Simple templates showing specific features. Files starting with . are ignored.
  • exports/: Generated JSON files from the /export command.

JSON Schema Guide

A standard configuration file follows this structure:

{
  "server_name": "My Community",
  "server_description": "Optional description",
  "roles": [
    {
      "name": "Admin",
      "hex": "#ff0000",
      "hoist": true,
      "mentionable": true,
      "permissions": {
        "administrator": true
      }
    }
  ],
  "categories": [
    {
      "name": "General",
      "channels": [
        {
          "name": "welcome",
          "type": "text",
          "permissions": {
            "@everyone": { "send_messages": false },
            "Admin": { "send_messages": true }
          }
        },
        { "name": "General Voice", "type": "voice" }
      ]
    }
  ]
}

Channel Types

Supported types are: text, voice, news, forum, stage.

JSON Syntax Reference

The JSON configuration is composed of top-level keys and nested objects. If a key is omitted, the bot uses its default behavior.

Top-Level Keys

  • server_name (String): Changes the name of the Discord server.
  • server_description (String): Changes the server description (requires Community settings).
  • roles (List): A list of role objects to be created.
  • categories (List): A list of category objects containing channels.

Role Object

  • name (String, Required): The name of the role.
  • hex (String): Hex color code (e.g., #3498db).
  • hoist (Boolean): If true, the role is displayed separately in the member list. Default: false.
  • mentionable (Boolean): If true, the role can be mentioned by anyone. Default: false.
  • permissions (Object): A set of server-wide permissions (Key: name, Value: true/false).

Category and Channel Objects

Categories contain a list of channels. Each channel object supports:

  • name (String, Required): The name of the channel.
  • type (String): The channel type. Options: text, voice, news, forum, stage. Default: text.
  • permissions (Object): Permission overrides for roles. Key: Role name or @everyone. Value: Object of permissions (true/false).

Permission Names

TerraDiscord uses the standard discord.py naming convention. Below are the most common permission names you can use in both roles and channel permissions:

General Permissions

  • administrator (Use with caution)
  • manage_guild (Manage Server)
  • manage_roles
  • manage_channels
  • view_audit_log
  • manage_webhooks
  • manage_emojis_and_stickers

Membership Permissions

  • kick_members
  • ban_members
  • moderate_members (Timeout)
  • create_instant_invite
  • change_nickname
  • manage_nicknames

Text Channel Permissions

  • view_channel
  • send_messages
  • send_tts_messages
  • manage_messages
  • embed_links
  • attach_files
  • read_message_history
  • mention_everyone
  • add_reactions
  • use_external_emojis

Voice Channel Permissions

  • connect
  • speak
  • stream (Video/Screen share)
  • use_embedded_activities
  • mute_members
  • deafen_members
  • move_members
  • priority_speaker

Slash Commands

All commands require Administrator permissions on the server.

  • /add [preset]: Adds roles and channels from the JSON to the current server. It does not delete existing data.
  • /set [preset]: Wipes the server (roles and channels) and rebuilds it from the JSON. The channel where the command is used is skipped during deletion.
  • /reset: Deletes all manageable roles and channels from the server.
  • /export: Scans the current server and saves the structure to a new JSON file in the exports/ folder.

Permissions

When defining permissions in JSON (either for roles or channel overrides), use the standard discord.py permission names (e.g., manage_messages, view_channel, connect). If a permission is not specified, it defaults to false for roles and neutral (default) for channel overrides.