Learning Path

Choose your learning path based on your experience and goals. Each path is designed to take you from where you are to where you want to be.

---

Choose Your Path

Complete Beginner
New to modding? Start here! JavaScript Developer
Know JS? Fast track! Java Mod Developer
Already know Hytale modding?

I Want To Build...
Jump to specific projects Reference / Quick Access
Know what you need?
Direct links to docs

---

Path 1: Complete Beginner

Perfect for: First time modding, basic programming knowledge
Goal: Create your own working server mods with confidence

Foundations

Setup & First Mod

1. Install SimpleScripting
2. Understand folder structure
3. Your First Mod Tutorial - BUILD THIS!
4. Understand the mod manifest

Exercise: Create a /greet command that says “Hello [player]!”

You’ll know: How to create, edit, and reload mods

---

Commands

1. Commands API reference
2. Tutorial: Commands with Arguments (coming soon)
3. Study: welcome-rewards example (focus on /playtime command)

Exercise: Create /heal and /feed commands

You’ll know: How to get command arguments and validate input

---

Events

1. Events API reference
2. Run events.knownEvents() to see all events
3. Study: welcome-rewards example (focus on join/leave events)

Exercise: Make a mod that logs when players chat

You’ll know: How to listen to game events

---

Database Basics

1. Database API reference
2. Study: welcome-rewards database code
3. Tutorial: Persistent Data (coming soon)

Exercise: Create a /note <text> command that saves notes per player

You’ll know: How to save and load data

---

Intermediate Skills

Players & Worlds

1. Players & Worlds API
2. UI & Messages - Make colorful messages
3. Study: welcome-rewards starter kit code

Exercise: Create /broadcast <message> with colors

You’ll know: How to find players and send formatted messages

---

Timers & Automation

1. Server API (timers)
2. Study: afk-manager example

Exercise: Create a mod that announces “Server restart in X” every 10 minutes

You’ll know: How to schedule repeating tasks

---

ECS Basics

1. ECS Overview
2. Components & Queries
3. Study: home-warps teleportation code

Exercise: Create /tphere <player> to teleport someone to you

You’ll know: How to work with entity positions

---

Final Project

Build a complete feature:

Pick one:

• Quest System: Track player quests with database, give rewards on completion
• Event System: Scheduled mini-games or competitions
• Leaderboard System: Track player stats and display rankings

Use:

• Commands
• Events
• Database
• UI messages
• One example mod as reference

You’ll know: How to combine all concepts into a working system!

---

What’s Next?

• Explore Advanced Topics
• Study example mods in detail
• Join the community and share your mods!

---

Path 2: JavaScript Developer

Perfect for: Already comfortable with JavaScript
Goal: Translate JS skills to Hytale mods quickly

Crash Course

Skip the basics, focus on differences:

1. Installation - Quick setup
2. Mod Layout - File structure
3. Your First Mod - 10-minute walkthrough
4. API Overview - What’s available

Key Differences from Node.js/Browser:

• No npm/package.json - direct .js files
• Use require('./file.js') for local modules only
• Global APIs instead of imports: commands, events, db, etc.
• ES5 syntax (no arrow functions, destructuring, async/await)

Exercise: Quick Test: Create /ping command

---

API Deep Dive

Study the APIs you’ll use most:

1. Events & Commands
2. Database
3. Players & Worlds
4. welcome-rewards full source

Mental Model:

// You write:
function onEnable() {
  commands.register('test', handler);
  events.on('playerready', handler);
  db.execute('CREATE TABLE...');
}

// Mods are isolated - each gets own:
// - Database (SQLite)
// - Rhino JavaScript context
// - Command/event registrations

Exercise: Quick Test: Build a /coin command with database to track flips

---

Production Patterns

1. Modules & Shared Services
2. simple-stats example - See require() usage
3. ECS Overview - Optional but powerful

Code Organization Pattern:

main.js

var utils = require('./utils.js');
var commands = require('./commands.js');

function onEnable() {
  commands.registerAll();
}

// commands.js
module.exports = {
  registerAll: function() {
    commands.register('help', helpCommand);
    commands.register('stats', statsCommand);
  }
};

Exercise: Build This: Multi-file mod with command router pattern

---

You’re Done!

You now know:

• ✅ How to create and structure mods
• ✅ All major APIs (commands, events, DB, players)
• ✅ Code organization with require()
• ✅ Production patterns from examples

Next: Pick a project from “I Want To Build…” and go!

---

Path 3: Java Mod Developer

Perfect for: Already developing Hytale mods in Java
Time commitment: 1 day (concepts only)
Goal: Understand how SimpleScripting complements Java mods

What You Need to Know

SimpleScripting is NOT a replacement for Java mods. It’s complementary.

Feature	Java Mod	SimpleScripting
Custom blocks/items	Java only	Not supported: Cannot define
Assets (models, textures)	Java only	Not supported: Cannot define
Server logic	Java	JavaScript
Commands	Java	JavaScript
Events	Java	JavaScript
Database	Manual	Built-in SQLite
Rapid iteration	Recompile	Edit & reload

Crash Course

1. Introduction - Design Philosophy
2. API Overview - How wrappers work
3. welcome-rewards example - See full implementation
4. Extensions System - Important! How to extend JS from Java

Key Concept - Wrapper Architecture:

// Java side (what you build)
public class MyExtension implements SimpleScriptingExtension {
    @Override
    public void onRegister(ExtensionContext context) {
        // Register your Java API for JS mods to use
        context.registerGlobalApi("myapi", (modId, runtime, logger) ->
            new MyJavaApi(logger)
        );
    }
}

// JavaScript side (what mod developers use)
function onEnable() {
    var result = myapi.doSomething("test"); // Your Java method
}

When to Use Each

Use Java When:

• Defining assets (blocks, items, models, UI files)
• Core gameplay mechanics
• Performance-critical operations
• Deep engine integration needed

Use SimpleScripting (JS) When:

• Server automation/logic
• Custom commands/events
• Rapid prototyping
• Non-developers need to customize

Use Both:

• Java defines the items/blocks/assets
• JS defines the gameplay logic using those assets

Practical Example: Shop System

// Java mod: Defines shop block, UI assets
public class ShopBlockMod extends JavaPlugin {
    // Register shop block, UI files
}

// JS mod: Shop logic/economy/transactions
function onEnable() {
  commands.register('shop', function(ctx) {
    // Open shop UI using Java-defined assets
    // Handle purchase logic in JS
    if (economy.withdraw(uuid, price)) {
      // Give item (defined in Java)
    }
  });
}

Creating Extensions

If you want JS mods to use your Java plugin:

1. Read: Extension System Guide
2. Study: EconomySS source code
3. Implement: SimpleScriptingExtension interface

---

I Want To Build…

Jump directly to project-specific guides:

Economy/Shop System

Requirements: EconomySS extension plugin + economy provider (VaultUnlocked/EliteEssentials)
Study:

• player-shops example
• ✅ Economy API (Extension)
• ✅ Database for prices

Pattern:

// 1. Check economy availability
if (!economy.isAvailable()) return;

// 2. Get prices from DB
var price = db.queryOne('SELECT price FROM items WHERE id = ?', [itemId]).price;

// 3. Validate and transact
if (economy.withdraw(uuid, price)) {
  // Give item
}

---

Teleportation System (Homes/Warps)

Study:

• home-warps example
• ✅ ECS Position/Teleport
• ✅ Database for locations

Pattern:

// Save location
var pos = ecs.getPosition(player);
db.execute('INSERT INTO homes VALUES (?, ?, ?, ?)', [name, pos.x, pos.y, pos.z]);

// Teleport to location
var home = db.queryOne('SELECT * FROM homes WHERE name = ?', [name]);
ecs.teleport(player, [home.x, home.y, home.z], [0, 0, 0]);

---

Statistics/Leaderboards

Study:

• simple-stats example
• ✅ Database queries
• ✅ Shared Services

Pattern:

// Track stat
db.execute('UPDATE stats SET kills = kills + 1 WHERE player = ?', [name]);

// Leaderboard
var top = db.query('SELECT player, kills FROM stats ORDER BY kills DESC LIMIT 10');

---

Mini-Games/Events

Study:

• welcome-rewards (timers)
• ✅ Server timers
• ✅ Events
• ✅ ECS (for gameplay)

Pattern:

var gameActive = false;
var participants = [];

commands.register('startgame', function() {
  gameActive = true;
  players.broadcast("Game starting in 30 seconds!");

  server.runLater(30000, function() {
    // Start game logic
  });
});

---

Reward Systems (Daily/Playtime)

Study:

• welcome-rewards (playtime tracking)
• ✅ Events (playerready)
• ✅ Database

Pattern:

events.on('playerready', function(event) {
  var lastClaim = db.queryOne('SELECT last_daily FROM rewards WHERE player = ?', [name]);
  var today = new Date().toDateString();

  if (lastClaim.last_daily !== today) {
    // Give daily reward
    db.execute('UPDATE rewards SET last_daily = ? WHERE player = ?', [today, name]);
  }
});

---

Custom Commands Suite

Study:

• ⭐ Your First Mod tutorial
• ✅ Commands API
• simple-stats (command routing)

Pattern:

// Multiple related commands
commands.register('heal', healCommand, { description: "Heal yourself" });
commands.register('feed', feedCommand, { description: "Feed yourself" });
commands.register('fly', flyCommand, { description: "Toggle fly" });

// Or subcommand routing
commands.register('admin', function(ctx) {
  var sub = ctx.args()[0];
  if (sub === 'heal') healCommand(ctx);
  else if (sub === 'tp') tpCommand(ctx);
});

---

Reference / Quick Access

I know what I need, take me there:

Core Concepts

• Mod Manifest (mod.json)
• Lifecycle Hooks
• Dependencies & Load Order

APIs

• Commands & Events
• Database (SQLite)
• Players & Worlds
• Inventory & Items
• Server, Net & Assets
• UI & Messages
• Economy (extension)
• Extensions System

ECS

• ECS Overview
• Components & Queries
• Systems & Events
• Spatial & Helpers

Advanced

• Modules & Shared Services
• Example Mods Source Code
• Current Limitations

Help

• FAQ
• Getting Started FAQ
• Troubleshooting

---

Advanced Topics

Once you’ve mastered the basics:

Cross-Mod Communication

• Shared Services
• Extension Events
• Study: simple-stats SharedServices

Extension Development

• Creating Extensions
• Provide TypeScript definitions
• Bundle example mods with extensions

Performance Optimization

• Database indexing
• Caching strategies
• Efficient event handlers
• Batch operations

Production Best Practices

• Error handling patterns
• Migration strategies
• Testing approaches
• Version management

---

Need Help?

• Stuck? Check the FAQ
• Errors? See Troubleshooting
• Examples? Study example mods
• Community: Join discussions on GitHub

---

Ready to start? Pick your path above and begin building!