Skip to content

README.md

Latest commit

ย 

History

History
138 lines (99 loc) ยท 4.23 KB

README.md

File metadata and controls

138 lines (99 loc) ยท 4.23 KB

SScript โ€” Server Scripting Language for Minecraft

SScript is a lightweight programming language for Minecraft server automation. Write scripts in Python-like syntax to execute commands, automate tasks, and control server behavior without touching Java code.

What It Does

Core Purpose: Execute automated commands and logic on your Minecraft server.

  • ๐ŸŽฏ Command Execution โ€” Run commands programmatically (/say, /give, /setblock, etc.)
  • โš™๏ธ Task Automation โ€” Run initialization scripts, scheduled tasks, bulk operations
  • ๐Ÿ”ง Server Logic โ€” React to player actions (join/leave, chat, block breaks, deaths, sleep)
  • ๐Ÿ“ Simple Syntax โ€” Python-like language anyone can learn
  • โšก Non-blocking โ€” Tasks run without freezing the server

Quick Start

1. Create a script auto-load in sscripts/load.ss:

log "Server starting up..."

func welcome():
    run "fill 10 50 10 -10 90 -10 air"
end

welcome()

2. Create event handler in sscripts/handlers.event.ss:

on player_join(player):
    run "say " + player.name + " joined"
    run "execute at " + player.name + " run fill ~10 50 ~10 ~-10 90 ~-10 air"
end

on player_chat(player, message):
    log player.name + ": " + message
end

3. Load and run:

/sscript run test.ss
/sscript debug on
/sscript debug off - no spam [Server]: ...

Done! Scripts execute without restart.

Language Features

  • Variables & Types: Strings, numbers, booleans, lists, objects
  • Control Flow: if/elif/else, for, while, try/catch
  • Functions: Define with func or def, call sync or async
  • Events: React to player actions, server events
  • Built-ins: 60+ functions for players, blocks, math, strings, files
  • Async Support: Background tasks with wait keyword

Commands

Execute scripts and control execution:

/sscript run <file>                    # Execute script
/sscript run <file> function <name>    # Call specific function
/sscript monitor [all|<id>| ]            # View running tasks
/sscript stop [all|<id>|<file>]               # Stop running task
/sscript reload [all|<id>|<file>]             # Restart task
/sscript debug [on|off]                # Toggle debug output server

Documentation

๐Ÿ“– Full documentation with examples and API reference:

Key Guides:

What Else?

Beyond command execution, SScript can:

  • ๐Ÿ“Š Store Data โ€” Global variables persist across restarts (globals.json)
  • ๐Ÿ“ก HTTP Requests โ€” Fetch data from APIs or send webhooks
  • ๐Ÿ’พ File I/O โ€” Read/write files and JSON
  • ๐ŸŽฎ Player Data โ€” Access health, gamemode, coordinates, NBT data
  • ๐Ÿท๏ธ Tag System โ€” Organize players with custom tags
  • ๐Ÿ” Selectors โ€” Query players dynamically (@a[tag=admin], @a[distance=..100])

Performance

  • โšก Tick-safe โ€” Tasks automatically spread across server ticks to prevent lag
  • ๐Ÿ”„ Non-blocking โ€” Event handlers run asynchronously (don't freeze gameplay)
  • ๐Ÿ’ช Limits โ€” 500 max processes, 20 spawn/tick, 50 statements/tick

Requirements

  • Java 21+
  • Fabric Loader 0.14+
  • Minecraft 1.21.11

Installation

  1. Download the mod JAR
  2. Put in mods/ folder
  3. Start server
  4. Place scripts in sscripts/

Example: Chat Logger

# sscripts/chat_logger.event.ss

func log_chat(player_name, message):
    file_mkdirs("sscripts/logs")
    line = "[" + player_name + "] " + message
    file_append("sscripts/logs/chat.log", line + "\n")
end

on player_chat(player, message):
    log_chat(player.name, message)
end

Links