Configuration Overview

Journey uses a comprehensive JSON-based configuration system that allows you to create complex, interactive experiences without writing code. This guide explains the overall structure and principles behind Journey’s configuration system.

Configuration Philosophy

Journey follows these configuration principles:

JSON-First: All content is defined in human-readable JSON files
Hot Reloading: Changes can be applied without server restarts
Modular Design: Each system has its own configuration structure
Validation: Built-in validation prevents invalid configurations
Version Control Friendly: Easily track changes and collaborate

Directory Structure

Journey creates this configuration hierarchy in your server’s config directory:

config/journey/
├── config.json              # Main server configuration
├── tasks/                   # Quest and objective definitions
│   ├── starter_quests.json
│   ├── regional_tasks.json
│   └── daily_challenges.json
├── zones/                   # Spatial area definitions
│   ├── towns.json
│   ├── dungeons.json
│   └── special_areas.json
├── levelables/              # Skill and progression systems
│   ├── combat_skills.json
│   ├── crafting_skills.json
│   └── exploration_skills.json
├── timelines/               # Scripted event sequences
│   ├── story_sequences.json
│   └── server_events.json
└── sources/                 # Task source configurations
    ├── npc_sources.json
    └── location_sources.json

Configuration Types

Main Configuration (`config.json`)

The main configuration file controls global Journey settings:

File Location: config/journey/config.json

{
  "debug": false,

  "subtask_separator_character": "<gold>┃</gold>",
  "task_description_separator_character": "<gold>┇</gold>",
  "subtask_description_separator": "<gold>╏</gold>",

  "quest_sidebar_title": "<gold>Quests",
  "task_description_max_length": 48,
  "subtask_description_max_length": 48,
  "max_tasks_shown": 2,
  "show_description_in_sidebar": false,

  "daily_reset_time": "00:00",
  "weekly_reset_day": "Monday",
  "monthly_reset_day": 1,
  "reset_time_zone": "UTC",
  "yearly_reset_date": "01-01",

  "completed_task_model": "minecraft:paper",
  "uncompleted_task_model": "minecraft:book",
  "back_button_model": "minecraft:arrow",
  "forward_button_model": "minecraft:arrow",
  "close_button_model": "minecraft:barrier",

  "journal_menu_title": "<blue>Journal",
  "journal_task_menu_title": "<blue>{task_name}",

  "server_name": "Server",
  "default_currency": "impactor:dollars",

  "levelable_mode": "multi_active",
  "levelable_max_count": -1,
  "levelable_switch_cooldown_seconds": 0,
  "levelable_respec_cost": 0.0,
  "levelable_respec_confirmation_required": true,
  "levelable_respec_currency": "impactor:dollars",

  "party_chat_provider": "auto",

  "party_enabled": true,
  "party_max_size": 10,
  "party_task_sync_enabled": true,

  "global_tasks_enabled": true,
  "global_tasks_central_server": "",
  "is_global_tasks_central_server": false
}

Configuration Reference

Debug Settings

Option	Type	Default	Description
`debug`	Boolean	`false`	Enable debug logging for troubleshooting

UI Customization

Separator Characters:

Option	Type	Default	Description
`subtask_separator_character`	String	`<gold>┃</gold>`	Character separating subtasks in UI
`task_description_separator_character`	String	`<gold>┇</gold>`	Character separating task descriptions
`subtask_description_separator`	String	`<gold>╏</gold>`	Character separating subtask descriptions

Sidebar Settings:

Option	Type	Default	Description
`quest_sidebar_title`	String	`<gold>Quests`	Title shown at top of sidebar
`task_description_max_length`	Integer	`48`	Maximum characters for task descriptions
`subtask_description_max_length`	Integer	`48`	Maximum characters for subtask descriptions
`max_tasks_shown`	Integer	`2`	Number of tasks displayed in sidebar
`show_description_in_sidebar`	Boolean	`false`	Show task descriptions in sidebar

Journal UI:

Option	Type	Default	Description
`journal_menu_title`	String	`<blue>Journal`	Title for journal menu
`journal_task_menu_title`	String	`<blue>{task_name}`	Title for task detail view (use `{task_name}` placeholder)
`completed_task_model`	String	`minecraft:paper`	Item model for completed tasks
`uncompleted_task_model`	String	`minecraft:book`	Item model for uncompleted tasks
`back_button_model`	String	`minecraft:arrow`	Item model for back button
`forward_button_model`	String	`minecraft:arrow`	Item model for forward button
`close_button_model`	String	`minecraft:barrier`	Item model for close button

Reset Times

Configure when repeatable tasks reset:

Option	Type	Default	Description
`daily_reset_time`	String	`00:00`	Time of day for daily resets (24-hour format)
`weekly_reset_day`	String	`Monday`	Day of week for weekly resets
`monthly_reset_day`	Integer	`1`	Day of month for monthly resets (1-31)
`yearly_reset_date`	String	`01-01`	Date for yearly resets (MM-DD format)
`reset_time_zone`	String	`UTC`	Timezone for all reset times

Economy Settings

Option	Type	Default	Description
`server_name`	String	`Server`	Display name for this server
`default_currency`	String	`impactor:dollars`	Default currency for rewards

Levelable System

Configure skill/progression system behavior:

Option	Type	Default	Description
`levelable_mode`	String	`multi_active`	Mode: `single_active`, `multi_active`, or `all_active`
`levelable_max_count`	Integer	`-1`	Max active levelables (-1 = unlimited)
`levelable_switch_cooldown_seconds`	Integer	`0`	Cooldown between switching active levelables
`levelable_respec_cost`	Double	`0.0`	Cost to reset a levelable
`levelable_respec_confirmation_required`	Boolean	`true`	Require confirmation for respec
`levelable_respec_currency`	String	`impactor:dollars`	Currency used for respec cost

Levelable Modes:

single_active - Only one levelable can be active at a time
multi_active - Multiple levelables active (limited by levelable_max_count)
all_active - All levelables always active

Party System

Configure party/group functionality:

Option	Type	Default	Description
`party_enabled`	Boolean	`true`	Enable the party system
`party_max_size`	Integer	`10`	Maximum players per party
`party_task_sync_enabled`	Boolean	`true`	Share task progress between party members
`party_chat_provider`	String	`auto`	Chat provider: `auto`, `carbon`, `styledchat`, or `vanilla`

Party Chat Providers:

auto - Automatically detect installed chat mod
carbon - Use CarbonChat integration
styledchat - Use StyledChat integration
vanilla - Use vanilla Minecraft chat

Global Tasks

Configure server-wide collaborative tasks:

Option	Type	Default	Description
`global_tasks_enabled`	Boolean	`true`	Enable global tasks system
`global_tasks_central_server`	String	`""`	Name of authoritative server for global tasks
`is_global_tasks_central_server`	Boolean	`false`	Is this server the central server?

See Global Tasks and Ceremony Integration for details.

Content Configurations

Each content type (tasks, zones, levelables, timelines) has its own configuration format:

Tasks define quests, objectives, and player activities Zones define spatial areas with custom behaviors Levelables define skill progression systems Timelines define scripted event sequences Sources define where and how tasks are distributed

Common Configuration Patterns

Naming Conventions

Journey uses consistent naming patterns across all configuration:

{
  "name": "<gold>Display Name",           // Formatted display name
  "description": ["Line 1", "Line 2"],   // Multi-line descriptions
  "id": "unique_identifier",              // Internal identifier
  "enabled": true,                        // Enable/disable toggle
  "metadata": {                           // Additional data
    "author": "ServerAdmin",
    "version": "1.0",
    "notes": "Configuration notes"
  }
}

Text Formatting

Journey supports full MiniMessage formatting for all text fields:

{
  "name": "<gold><bold>Epic Quest",
  "description": [
    "<yellow>Complete this <blue>challenging</blue> quest",
    "<gray>Rewards: <green>500 PokéDollars"
  ]
}

Conditional Logic

Most configurations support Molang expressions for conditional logic:

{
  "start_requirement": "q.player.levelable_level('trainer') >= 10 && q.player.has_flag('tutorial_complete')",
  "filter": "q.pokemon.species.identifier == 'cobblemon:pikachu' && q.pokemon.level >= 25"
}

Configuration Validation

Journey validates all configurations on load and provides detailed error messages:

Common Validation Issues

Invalid JSON Syntax

Error in tasks/my_task.json line 15: Expected ',' or '}' after property value

Missing Required Fields

Error in tasks/my_task.json: Required field 'name' is missing

Invalid Data Types

Error in zones/my_zone.json: Field 'radius' must be a number, got string

Invalid References

Error in tasks/my_task.json: Referenced reward type 'invalid_type' does not exist

Configuration Management

Hot Reloading

Reload configurations without restarting the server:

/journey reload
/journey reload tasks
/journey reload zones
/journey reload levelables
/journey reload timelines

Validation Commands

Validate configurations before applying:

/journey validate                    # Validate all configs
/journey validate tasks             # Validate only task configs
/journey validate tasks/my_task     # Validate specific file

Backup and Versioning

Journey supports configuration backups and versioning:

{
  "version": "2.1.0",
  "changelog": [
    "Added new quest chain for Route 1",
    "Fixed rewards for daily challenges",
    "Updated zone boundaries for Viridian City"
  ],
  "backup": {
    "auto_backup": true,
    "backup_count": 10,
    "backup_on_reload": true
  }
}

Best Practices

Organization

Group Related Content

Keep related tasks in the same file
Use descriptive file names
Organize by region, story arc, or feature

Use Consistent Naming

Prefix IDs with category (quest_, zone_, skill_)
Use snake_case for IDs
Use descriptive names for display text

Documentation

Add Metadata

{
  "metadata": {
    "author": "ServerAdmin",
    "created": "2024-01-15",
    "last_modified": "2024-03-20",
    "description": "Starter quest chain for new players",
    "dependencies": ["tutorial_complete"],
    "testing_notes": "Tested with 10 new players"
  }
}

Comment with Descriptions

{
  "name": "Defeat Team Rocket",
  "description": [
    "Help Officer Jenny stop Team Rocket's latest scheme",
    "<yellow>Prerequisites: Complete 'Missing Pokémon' quest",
    "<gray>Estimated time: 30 minutes"
  ]
}

Performance

Optimize Update Intervals

Use longer intervals for background tasks
Avoid unnecessary complex filters
Limit concurrent active timelines

Efficient Zone Design

Avoid overlapping zones where possible
Use appropriate shapes for your needs
Consider using area filters instead of complex zones

Environment-Specific Configurations

Development vs Production

Use different configurations for testing and live servers:

Development (config/journey/dev/)

Debug logging enabled
Reduced requirements
Test rewards and items

Production (config/journey/prod/)

Debug logging disabled
Balanced requirements
Final rewards and progression

Multi-Server Setup

Journey supports shared configurations across multiple servers:

{
  "shared_config": {
    "enabled": true,
    "source": "network_drive/journey_configs/",
    "sync_interval": 300,
    "override_local": false
  }
}

Configuration Security

Permission-Based Access

Control who can modify configurations:

{
  "security": {
    "require_permission": true,
    "modify_permission": "journey.admin",
    "reload_permission": "journey.reload",
    "validate_on_load": true,
    "backup_on_change": true
  }
}

Sensitive Data Handling

Never include sensitive information in configurations:

Use environment variables for API keys
Reference external secure storage for passwords
Use permission systems for access control

Next Steps

Now that you understand Journey’s configuration system:

Learn about Tasks - Create your first quest
Explore Zones - Define spatial areas
Set up Levelables - Create progression systems
Master Molang Scripting - Add advanced logic

The configuration system is designed to grow with your server’s complexity while remaining manageable and maintainable. Start simple and build up to more complex systems as you become comfortable with each component!

Configuration Overview

Configuration Overview

Configuration Philosophy

Directory Structure

Configuration Types

Main Configuration (config.json)

Configuration Reference

Debug Settings

UI Customization

Reset Times

Economy Settings

Levelable System

Party System

Global Tasks

Content Configurations

Common Configuration Patterns

Naming Conventions

Text Formatting

Conditional Logic

Configuration Validation

Common Validation Issues

Configuration Management

Hot Reloading

Validation Commands

Backup and Versioning

Best Practices

Organization

Documentation

Performance

Environment-Specific Configurations

Development vs Production

Multi-Server Setup

Configuration Security

Permission-Based Access

Sensitive Data Handling

Next Steps

Main Configuration (`config.json`)