Skip to main content

StarScript

StarScript transforms Minecraft into a powerful story-driven experience engine. It enables creators to build branching narratives, interactive quests, and dynamic storytelling experiences entirely through JSON configuration, without requiring Java programming knowledge.

Vision and Purpose​

StarScript was created to bridge the gap between traditional Minecraft gameplay and narrative-driven experiences. While Minecraft excels at sandbox creativity, telling structured stories with branching paths and player choices has historically required significant programming expertise. StarScript changes that by providing a complete storytelling framework accessible to content creators, world builders, and story writers.

Core Philosophy​

JSON-Driven Design​

Every aspect of a story is defined in JSON files. This approach offers several advantages:

  • Accessibility: Non-programmers can create complex narratives
  • Versioning: Stories can be tracked in version control
  • Sharing: Stories are data packs that can be easily distributed
  • Iteration: Quick changes without recompiling code
  • Documentation: JSON structure serves as self-documenting format

Event-Driven Architecture​

StarScript uses an efficient event-driven system where triggers only execute when relevant game events occur. This design ensures:

  • Minimal performance overhead
  • Scalability to hundreds of concurrent stories
  • No polling or constant checking
  • Clean integration with Minecraft's event system

Player-Centric State Management​

Each player maintains their own story state independently. This allows:

  • Multiplayer servers where players experience different story paths
  • No interference between players' narrative choices
  • Individual save systems
  • Flexible difficulty and pacing per player

Story Structure​

Nodes as Building Blocks​

Stories are composed of nodes, each representing a scene, dialogue, or decision point. Nodes contain:

Core Properties

  • id: Unique identifier for the node
  • type: Node category (dialogue, journal, discovery, ending)
  • text: Array of text lines to display
  • speaker: Optional character name
  • choices: Array of player choices
  • triggers: Conditions that advance the story automatically
  • on_start: Actions executed when entering the node
  • on_complete: Actions executed when leaving the node
  • requires: Conditions that must be met to access the node

Example Node

{
  "id": "village_elder",
  "type": "dialogue",
  "speaker": "Elder Thoran",
  "text": [
    "Greetings, traveler. Dark times have befallen our village.",
    "The ancient artifact has been stolen by raiders."
  ],
  "choices": [
    {
      "text": "I will help you recover it",
      "next": "accept_quest",
      "actions": [
        {"type": "set_flag", "flag": "quest_accepted"}
      ]
    },
    {
      "text": "This is not my concern",
      "next": "reject_quest",
      "requires": ["var:reputation<50"]
    }
  ]
}

Branching Narratives​

StarScript supports complex branching through:

Linear Paths: Sequential story progression Conditional Branches: Paths based on player state Parallel Tracks: Multiple concurrent storylines Convergent Paths: Different routes leading to common outcomes Multiple Endings: Varied conclusions based on player choices

Variable System​

Three types of variables track story state:

Flags (Boolean)

Simple true/false markers for story events:

{"type": "set_flag", "flag": "dragon_defeated"}
{"type": "clear_flag", "flag": "in_combat"}

// Check in requirements
"requires": ["flag:dragon_defeated"]

Integers

Numeric values for scores, counts, reputation:

{"type": "set_var", "name": "gold", "value": 100}
{"type": "increment_var", "name": "reputation", "amount": 10}
{"type": "decrement_var", "name": "health_potions", "amount": 1}

// Check in requirements
"requires": ["var:gold>=50", "var:reputation>80"]

Strings

Text values for names, factions, status:

{"type": "set_var", "name": "faction", "value": "rebels"}
{"type": "set_var", "name": "title", "value": "Knight"}

// Check in requirements
"requires": ["var:faction=rebels"]

Trigger System​

Triggers cause story progression based on game events rather than explicit player choices.

Player Action Triggers​

Item Interaction

{
  "type": "item_used",
  "item": "minecraft:diamond_pickaxe",
  "next": "discovered_diamonds"
}

Block Interaction

{
  "type": "block_interact",
  "block": "minecraft:lectern",
  "next": "found_ancient_text"
}

Crafting

{
  "type": "crafting",
  "item": "minecraft:enchanting_table",
  "next": "learned_enchanting"
}

Combat Triggers​

Entity Kills

{
  "type": "kill_entity",
  "entity": "minecraft:zombie",
  "count": 10,
  "next": "cleared_zombies"
}

Boss Defeats

{
  "type": "boss_kill",
  "entity": "minecraft:ender_dragon",
  "next": "dragon_slayer"
}

Exploration Triggers​

Biome Discovery

{
  "type": "biome_discover",
  "biome": "minecraft:desert_temple",
  "next": "found_temple"
}

Structure Entry

{
  "type": "structure_enter",
  "structure": "*stronghold*",
  "next": "discovered_stronghold"
}

Proximity

{
  "type": "proximity",
  "x": 1000,
  "y": 64,
  "z": -500,
  "radius": 20,
  "next": "arrived_at_ruins"
}

Advanced Triggers​

Time-Based

{
  "type": "time_change",
  "time": "midnight",
  "next": "midnight_event"
}

{
  "type": "day_count",
  "day": 7,
  "next": "week_passed"
}

Dimension Changes

{
  "type": "dimension_enter",
  "dimension": "minecraft:the_nether",
  "next": "entered_nether"
}

Health/Status

{
  "type": "health_below",
  "threshold": 6.0,
  "next": "low_health_event"
}

Action System​

Actions execute automatically when nodes activate or choices are made.

Item Actions​

{"type": "give_item", "item": "minecraft:diamond_sword", "count": 1}
{"type": "remove_item", "item": "minecraft:key", "count": 1}
{"type": "clear_inventory"}

Player Manipulation​

{"type": "teleport", "x": 100, "y": 64, "z": 200, "dimension": "minecraft:overworld"}
{"type": "set_spawn", "x": 50, "y": 70, "z": 150}
{"type": "heal", "amount": 20.0}
{"type": "damage", "amount": 5.0}

World Interaction​

{"type": "run_command", "command": "time set day"}
{"type": "set_block", "x": 100, "y": 64, "z": 200, "block": "minecraft:diamond_block"}
{"type": "spawn_entity", "entity": "minecraft:villager", "x": 100, "y": 64, "z": 200}

Effects and Audio​

{"type": "play_sound", "sound": "minecraft:entity.ender_dragon.roar", "volume": 1.0}
{"type": "add_effect", "effect": "minecraft:strength", "duration": 600, "amplifier": 1}
{"type": "particle", "particle": "minecraft:flame", "x": 100, "y": 65, "z": 200}

Cinematic Actions​

{
  "type": "scene",
  "transition": "fade",
  "direction": "in",
  "duration": 60,
  "overlay": "vignette",
  "intensity": 0.7
}

Boss System​

StarScript includes an advanced boss encounter system introduced in version 0.7.0.

Boss Phases​

Bosses can have multiple phases triggered by health thresholds:

{
  "boss_phases": [
    {
      "health_threshold": 0.75,
      "node_id": "boss_phase_2",
      "actions": [
        {"type": "play_sound", "sound": "entity.ender_dragon.roar"},
        {"type": "send_message", "message": "§cThe boss grows stronger!"}
      ]
    },
    {
      "health_threshold": 0.25,
      "node_id": "boss_desperate",
      "arena_effects": ["lightning", "fire"]
    }
  ]
}

Arena Locking​

Prevent players from escaping boss fights:

{
  "arena": {
    "center_x": 100,
    "center_z": 200,
    "radius": 50,
    "locked": true,
    "barrier_type": "bedrock"
  }
}

Custom Bosses​

Define bosses with enhanced attributes:

{
  "custom_bosses": [
    {
      "id": "shadow_lord",
      "name": "§4§lShadow Lord",
      "base_entity": "minecraft:wither_skeleton",
      "health_multiplier": 5.0,
      "damage_multiplier": 2.0,
      "speed_multiplier": 1.3,
      "abilities": ["regeneration", "strength"],
      "show_boss_bar": true,
      "drops": [
        {"item": "minecraft:diamond", "min_count": 5, "max_count": 10}
      ]
    }
  ]
}

Death Consequences​

Ten different death consequence types:

  • XP loss
  • Item loss
  • Curse effects
  • Corruption
  • Teleportation
  • Stat reduction
  • Quest failure
  • Story branching
  • Respawn delay
  • Permanent debuffs

GUI System​

Display Modes​

Traditional Mode

Centered dialogue box with choices displayed as buttons below the text. This mode works well for:

  • Quest dialogues
  • NPC conversations
  • Information delivery
  • Multiple choice selections

Visual Novel Mode

Text positioned at the bottom of the screen with optional character names, creating an immersive reading experience. Best for:

  • Story-heavy narratives
  • Character development
  • Dramatic scenes
  • Cinematic sequences

Customization​

Each node can have custom styling:

{
  "gui_style": {
    "panel_color": "#DD1a1a2e",
    "border_color": "#FF16c784",
    "text_color": "#FFFFFFFF",
    "text_position": "bottom",
    "button_position": "middle",
    "typewriter_speed": 20
  }
}

Text Effects​

Typewriter Effect

Text appears character by character with adjustable speed:

{"typewriter_delay_ms": 50}

Text Formatting

Support for Minecraft formatting codes:

§l - Bold
§o - Italic
§n - Underline
§4 - Color (red)

Button Layouts​

Automatic layout adjustment based on number of choices:

  • 1-2 choices: Vertical stack
  • 3-4 choices: Side-by-side
  • 5+ choices: Scrollable list

Builder Pattern API​

Version 1.0.0 introduced a programmatic API for creating stories through code.

Story Builder​

Story story = new StoryBuilder()
    .setId("epic_quest")
    .setName("The Epic Quest")
    .setDescription("A grand adventure awaits")
    .setStartNode("intro")
    .addNode(new StoryNodeBuilder()
        .setId("intro")
        .setType(NodeType.DIALOGUE)
        .addText("Welcome, brave adventurer!")
        .addChoice(new StoryChoiceBuilder()
            .setText("I accept the quest!")
            .setNext("quest_start")
            .addAction(StoryActionBuilder.giveItem("quest_token", 1).build())
            .build())
        .build())
    .build();

Factory Methods​

33 factory methods for common operations:

// Actions
StoryActionBuilder.giveItem("diamond", 5)
StoryActionBuilder.teleport(100, 64, 200)
StoryActionBuilder.playSound("entity.player.levelup")
StoryActionBuilder.sendMessage("Quest Complete!")

// Triggers
StoryTriggerBuilder.onBossKill("ender_dragon", "victory")
StoryTriggerBuilder.onProximity(100, 64, 200, 20, "arrived")
StoryTriggerBuilder.onItemPickup("special_key", "found_key")

Nested Builders​

Support for complex configurations:

.addChoice(new StoryChoiceBuilder()
    .setText("Ancient wisdom")
    .setNext("wisdom_path")
    .setGuiStyle(new GuiStyleBuilder()
        .setPanelColor("#1a1a2e")
        .setBorderColor("#16c784")
        .build())
    .addTextEffect(new TextEffectBuilder()
        .setTypewriterSpeed(30)
        .setColor("#FFD700")
        .build())
    .build())

Modifying Existing Stories​

Story modified = new StoryBuilder()
    .from(existingStory)
    .setDescription("Updated description")
    .addNode(newNode)
    .build();

Relic System​

Version 0.7.0 introduced a relic progression system.

Relic States​

Relics transform through states:

  • Dormant: Initial state, basic functionality
  • Awakened: Enhanced powers unlocked
  • Corrupted: Dark powers with consequences

Relic Crafting​

Progressive crafting system:

{
  "relic_crafting": {
    "id": "ancient_sword",
    "recipe": [
      {"item": "minecraft:diamond_sword", "count": 1},
      {"item": "minecraft:nether_star", "count": 1},
      {"item": "custom:ancient_fragment", "count": 3}
    ],
    "result_state": "awakened",
    "requires_node": "altar_discovered"
  }
}

Recipe Unlocking​

Control when players can craft items:

{
  "type": "unlock_recipe",
  "recipe": "custom:ancient_sword",
  "requires": ["flag:altar_activated", "var:wisdom>=50"]
}

World Integration​

Soft Discovery​

Environmental hints guide players without explicit markers:

{
  "soft_discovery": {
    "sounds": ["ambient.cave"],
    "particles": ["minecraft:smoke"],
    "frequency": 100,
    "radius": 50
  }
}

Region Memory​

World regions remember story events:

{
  "region": {
    "min_x": -100,
    "max_x": 100,
    "min_z": -100,
    "max_z": 100,
    "state": "corrupted",
    "effects": ["darkness", "fog"]
  }
}

Structure Variants​

Buildings transform based on story progression:

{
  "structure_variants": {
    "village_temple": [
      {"state": "pristine", "structure": "temple_clean"},
      {"state": "corrupted", "structure": "temple_dark"},
      {"state": "destroyed", "structure": "temple_ruins"}
    ]
  }
}

Save System​

Players can save and load progress across 10 slots.

Saving​

/story save <slot_number>

Saves:

  • Current node position
  • All flags
  • All variables
  • Completion status
  • Timestamp

Loading​

/story load <slot_number>

Auto-Save​

Automatic saving on:

  • Player disconnect
  • Server shutdown
  • Node completion
  • Major story events

Performance Optimization​

Rendering Optimizations​

Version 0.7.0 included major rendering improvements:

  • Multi-layer rendering pipeline
  • Adaptive Bezier curve segments
  • Smart pin label rendering
  • Grid depth perception
  • Efficient connection rendering

Benchmarks:

  • Frame time impact: < 5ms
  • 100+ triggers: < 1ms per tick
  • Story hot-reload: < 100ms

Memory Management​

  • Lazy loading of story files
  • Efficient state caching
  • Automatic cleanup on disconnect
  • Smart trigger registration

Network Optimization​

  • Delta-based state updates
  • Compressed packet transmission
  • Batched updates
  • Client-side prediction

Blueprint Editor​

Visual node-based story editor within Minecraft.

Features​

  • Modern gradient background
  • Multi-layer grid system
  • Card-style nodes with shadows
  • Animated connections with pulse effects
  • Minimap for navigation
  • Glass morphism info panel
  • Rich multi-line tooltips
  • Drag-and-drop interface

Node Palette​

Pre-configured node types:

  • Dialogue nodes
  • Choice nodes
  • Action nodes
  • Trigger nodes
  • Conditional nodes

Real-Time Preview​

Changes visible immediately:

  • Live text updates
  • Dynamic connection rendering
  • Interactive testing mode
  • Error highlighting

Development Integration​

Custom Mod Integration​

// Start stories from your mod
StoryEngine.activateNode(player, "mymod:quest", "intro");

// Check player state
StoryState state = StoryStateManager.getState(player, "mymod:quest");
if (state.hasFlag("completed")) {
    // Reward logic
}

// Set variables
StoryStateManager.setIntVariable(player, "mymod:quest", "score", 100);

Event Listeners​

Listen for story events:

@EventHandler
public void onStoryComplete(StoryCompleteEvent event) {
    Player player = event.getPlayer();
    String storyId = event.getStoryId();
    // Custom logic
}

Custom Triggers​

Register custom trigger types:

TriggerRegistry.register("custom_trigger", 
    new CustomTriggerHandler());

Commands​

Player Commands​

/story list                    - View available stories
/story start <id>             - Begin a story
/story stop                   - End current story
/story progress               - Show progress
/story save <slot>           - Save to slot
/story load <slot>           - Load from slot

Admin Commands​

/story reload                 - Reload all stories
/story debug                  - Toggle debug mode
/story flag set <story> <flag> - Set flag
/story var set <story> <name> <value> - Set variable
/story choose <story> <node> <choice> - Force choice

Debug Commands​

/story scene fade_in          - Test effects
/story trigger <type>         - Test triggers
/story state <player>         - View player state

Configuration​

Main Configuration​

Located at .minecraft/config/starscript.json:

{
  "debugMode": false,
  "showObjectivesHud": true,
  "autoSaveEnabled": true,
  "textSpeed": 20,
  "uiScale": 1.0,
  "maxSaveSlots": 10,
  "enableTelemetry": false
}

Per-Story Configuration​

Each story can override global settings:

{
  "id": "mystory",
  "config": {
    "allowSaving": true,
    "showProgress": true,
    "timeout": 0
  }
}

Best Practices​

Story Design​

  • Start simple, add complexity gradually
  • Test all choice combinations
  • Provide clear player feedback
  • Balance text length for readability
  • Use scene effects sparingly for impact

Performance​

  • Limit active triggers per player
  • Use event-based triggers over proximity when possible
  • Clear unused flags and variables
  • Combine related triggers in single nodes

Player Experience​

  • Show consequences of choices
  • Provide meaningful decisions
  • Balance difficulty appropriately
  • Test with real players
  • Gather feedback early

Requirements​

  • Minecraft: 1.21.11
  • Fabric Loader: 0.18.2+
  • Fabric API: 0.139.4+
  • Java: 21+

Optional:

  • ModMenu (for config GUI)
  • YACL (for advanced config)

License​

StarScript is released under the MIT License, allowing free use, modification, and distribution with proper attribution.

Community​

  • GitHub Repository: For issues and contributions
  • Documentation: Complete guides in the docs folder
  • Examples: Sample stories in resources
  • Discord: Community support and discussion