Discraft Documentation

Discraft is a small tool for defining Discord server structures as portable JSON. Create a setup visually, write it yourself, or generate it with the Discraft SDK. Export the definition and install it into a Discord server using the Discraft Discord app.

Visual → JSON → Discord
Code   → JSON → Discord
AI     → JSON → Discord

---

Quick Start

1. Open Discraft Designer

2. Create roles, categories, and channels using the visual tree

3. Export your setup as a .discraft.json file

4. Add the Discraft bot to your Discord server

5. Use /install and upload your JSON file

6. Done.

---

JSON Format

Overview

Every Discraft definition is a JSON file with this structure:

{
  "format": "discraft",
  "version": 1,
  "name": "My Server",
  "roles": [],
  "categories": [],
  "channels": []
}

• format — Must be "discraft".
• version — Must be 1.
• name — Server name (required, max 100 characters).
• roles — Array of role definitions (optional).
• categories — Array of category definitions with nested channels (optional).
• channels — Array of top-level channels not inside any category (optional).

Roles

{
  "name": "Moderator",
  "color": "#f39c12",
  "hoist": true,
  "mentionable": true,
  "permissions": {
    "manage_messages": true,
    "kick_members": true
  }
}

Property	Type	Required	Description
name	string	Yes	Role name (max 100 chars)
color	string	No	Hex color code (e.g. #ff0000)
hoist	boolean	No	Display separately in member list
mentionable	boolean	No	Allow anyone to mention this role
permissions	object	No	Server-wide permissions

Categories

{
  "name": "Community",
  "position": 0,
  "permissions": {
    "@everyone": { "view": true }
  },
  "channels": [
    { "name": "general", "type": "text" },
    { "name": "Gaming", "type": "voice" }
  ]
}

Property	Type	Required	Description
name	string	Yes	Category name (max 100 chars)
position	integer	No	Sort position (0-based)
permissions	object	No	Permission overwrites per role
channels	array	No	Channels inside this category

Channels

{
  "name": "general",
  "type": "text",
  "topic": "Welcome to the community",
  "position": 0,
  "permissions": {
    "@everyone": { "send": false },
    "Moderator": { "send": true }
  }
}

Property	Type	Required	Description
name	string	Yes	Channel name (max 100 chars)
type	string	Yes	"text" or "voice"
topic	string	No	Channel topic (text only, max 1024 chars)
position	integer	No	Sort position (0-based)
permissions	object	No	Permission overwrites per role

Permissions

Role Permissions (server-wide)

Used in the permissions field of a role definition:

Permission	Description
administrator	Full admin access
manage_guild	Manage server settings
manage_channels	Create, edit, delete channels
manage_roles	Create, edit, delete roles
manage_messages	Delete and pin messages
kick_members	Kick members
ban_members	Ban members
view_audit_log	View audit log
create_invite	Create invites
change_nickname	Change own nickname
manage_nicknames	Change other members' nicknames
manage_emojis	Manage server emojis
manage_webhooks	Manage webhooks
view	View channels
send	Send messages
send_tts	Send TTS messages
embed_links	Embed links
attach_files	Attach files
read_history	Read message history
mention_everyone	Mention @everyone
use_external_emojis	Use external emojis
add_reactions	Add reactions
connect	Connect to voice
speak	Speak in voice
mute_members	Mute members in voice
deafen_members	Deafen members in voice
move_members	Move members between voice channels
use_vad	Use voice activity detection
priority_speaker	Priority speaker in voice

Channel Permissions (overwrites)

Used in the permissions field of a category or channel definition. These override role-level permissions for specific channels.

{
  "permissions": {
    "@everyone": {
      "view": false
    },
    "Moderator": {
      "view": true,
      "send": true
    }
  }
}

• Keys are role names (not IDs).
• @everyone refers to the default role.
• Values are true (allow) or false (deny).
• Omitting a permission means "inherit" (no overwrite).

---

SDK

The Discraft SDK is a JavaScript builder class for generating Discraft JSON definitions programmatically.

Usage

const server = new Discraft("Gaming Community");

server.role("Admin", { color: "#ff0000" });
server.role("Moderator", {
    color: "#f39c12",
    hoist: true,
    permissions: { manage_messages: true, kick_members: true }
});
server.role("Member");

server.category("Community", category => {
    category.text("general", { topic: "Welcome!" });
    category.text("media");
    category.voice("Gaming");
});

server.category("Staff", category => {
    category.text("staff-chat");
    category.voice("Staff Voice");
});

console.log(server.toJSON());

API

Method	Description
new Discraft(name)	Create a new server definition
.role(name, options?)	Add a role
.category(name, builder?)	Add a category with optional builder callback
.text(name, options?)	Add a top-level text channel
.voice(name, options?)	Add a top-level voice channel
.toJSON()	Export as a JavaScript object
.toString()	Export as formatted JSON string

Category Builder

Inside a .category() callback:

Method	Description
.text(name, options?)	Add a text channel
.voice(name, options?)	Add a voice channel
.permissions(overwrites)	Set permission overwrites
.position(pos)	Set sort position

Code Generation

The designer can export your visual design as SDK code using Discraft.generateCode(setup).

---

Discord Bot

Installation

1. Add the Discraft bot to your server

2. The bot requires Manage Channels and Manage Roles permissions

Commands

/install file:

Upload a .discraft.json file to install the server setup.

The installer:

• Validates the JSON format and schema
• Checks bot permissions
• Creates roles in order
• Creates categories
• Creates channels inside categories
• Applies permission overwrites
• Reports results

/help

Shows brief usage information.

Behavior

• Additive only — The installer only adds missing items. It never deletes existing channels, roles, or categories.
• Collision handling — If a role or channel already exists (by name), it is skipped.
• Permission hierarchy — The bot respects Discord's role hierarchy. It cannot modify roles above its own.

---

Examples

Basic Server

{
  "format": "discraft",
  "version": 1,
  "name": "My Server",
  "roles": [
    { "name": "Admin", "color": "#e74c3c" },
    { "name": "Member", "color": "#3498db" }
  ],
  "categories": [
    {
      "name": "General",
      "channels": [
        { "name": "welcome", "type": "text", "topic": "Welcome!" },
        { "name": "general", "type": "text" },
        { "name": "General", "type": "voice" }
      ]
    }
  ]
}

Private Staff Category

{
  "name": "Staff",
  "permissions": {
    "@everyone": { "view": false },
    "Moderator": { "view": true, "send": true },
    "Admin": { "view": true, "send": true }
  },
  "channels": [
    { "name": "staff-chat", "type": "text" },
    { "name": "mod-logs", "type": "text" },
    { "name": "Staff Voice", "type": "voice" }
  ]
}

Read-Only Announcements

{
  "name": "announcements",
  "type": "text",
  "topic": "Server announcements",
  "permissions": {
    "@everyone": { "send": false },
    "Admin": { "send": true }
  }
}

---

AI Support

Discraft definitions are designed to be AI-friendly. You can tell any AI coding assistant:

Create a Discraft JSON definition for a Minecraft community with Admin, Moderator, and Member roles, an Information category with rules and announcements channels, and a Community category with general chat and voice.

The AI generates valid Discraft JSON. You can validate it using the designer or the /api/validate endpoint.

---

Limits

Limit	Value
Maximum roles	250
Maximum categories	50
Maximum channels	500
Role/channel name length	100 characters
Channel topic length	1024 characters
JSON file size	100 KB

---

Schema

The full JSON Schema is available at:

https://Discraft.iH4xz.pro/schema/v1.json

The permission mapping reference:

https://Discraft.iH4xz.pro/schema/permissions.json