RunestoneSkills

📌 Compatibility

• Platform: Paper
• Minecraft: 1.21.11
• Java: 21
• Required: RunestoneCore
• Soft-Dependencies: Oraxen

🚀 Quick Start

1. Drop RunestoneCore.jar and RunestoneSkills.jar into /plugins/
2. Start the server once to generate config and data files
3. Tune settings in plugins/RunestoneSkills/
4. Restart the server ✅

Avoid /reload when possible. Prefer a full restart or the module reload command where appropriate.

🧩 What’s Included

🏗️ Skill Engine & Architecture

• Clean module-based skill architecture
• One addon plugin that registers multiple skills into RunestoneCore
• Per-skill enable/disable behavior through YAML
• Shared integration through RunestoneCore’s public API
• Enabled skills register into the shared /skills output
• Designed for future expansion without rebuilding the base skill engine

📈 Progression & Leveling

• Shared profession XP curve through RunestoneCore integration
• Per-skill skill_id, display_name, and max_level
• Consistent registration into RunestoneCore’s skills registry
• Shared add / set total XP flow for each skill through the core registry bridge
• Ready for future profession expansion and addon growth

💾 Storage & Persistence

• Persistent YAML-backed skill XP storage in data.yml
• Separate exploration discovery persistence in exploration_data.yml
• Shared placed-block anti-abuse tracking in placed_blocks.yml
• Safe load/save lifecycle on enable, disable, and reload
• Runtime-generated config/data files that preserve tuned values

🛡️ Anti-Exploit & Abuse Prevention

• Player-placed block protection where applicable
• Creative/spectator filtering
• Per-skill interval and rate-limit controls
• Natural-only checks where appropriate
• Tool validation depending on the skill
• Forestry natural tree-context validation
• Mining placed-scope controls
• Exploration anti-teleport / anti-flight / anti-glide / anti-vehicle protections
• Hunting protections against babies, named mobs, tamed mobs, and blocked spawn reasons
• Farming maturity checks and base-segment protections
• Foraging placed-aware vegetation gathering rules

🎛️ Performance & Optimization

• Avoids heavy exploration move-event spam
• Scheduled/background exploration sampling
• Rate-limited XP flow where configured
• Shared placed-block tracker with autosave support
• Skill logic remains split across dedicated listeners, configs, and XP managers
• Lightweight dependency footprint outside RunestoneCore and optional Oraxen support

🔄 Updater Support

• Built-in Hangar version checking
• Configurable startup checks
• Configurable repeating check interval
• Optional OP/admin update notifications
• Optional auto-download to Paper’s update folder for next restart

🧱 Oraxen Support

• Optional Oraxen integration for custom mining blocks
• Built-in Oraxen asset installer
• Bundled RunestoneMMO Oraxen item/block content packaged with the addon
• Server-startup installer support
• Manual asset installation command support
• Diagnostics command for Oraxen/bundled asset checks

🌍 Mining Worldgen / Oregen

• Separate oregen_system.yml for mining worldgen config
• Additive custom ore generation support for new chunks
• Oraxen-backed custom ore placement support
• Mining XP remains controlled through mining.yml
• Worldgen is separated from skill XP config for cleaner maintenance

🧩 Skill Modules

Each skill is configured independently under plugins/RunestoneSkills/.

⛏️ Mining

Config: mining.yml

• XP for vanilla mineable pickaxe blocks
• Per-material overrides
• Correct-tool enforcement
• Fortune and Silk Touch multiplier support
• Optional Oraxen block XP mappings
• Player-placed block denial and anti-abuse controls
• Separate additive custom ore generation support via oregen_system.yml

🌲 Forestry

Config: forestry.yml

• XP for natural tree blocks and nether stem/hyphae families
• Axe/tool enforcement support
• Tree-context validation using nearby leaves or wart blocks
• Player-placed block denial
• Rate limiting and anti-abuse controls
• Supports overworld and nether tree families
• Includes broader natural tree handling for more complex tree structures

🎣 Fishing

Config: fishing.yml

• XP for fish, treasure, junk, and caught entities
• Rod requirement
• Optional open-water validation
• Catch interval protections and rate limits
• Per-material and per-entity XP overrides

🏹 Hunting

Config: hunting.yml

• XP for configured passive mobs
• Spawn-reason filtering
• Ignores babies, named mobs, and tamed mobs
• Per-entity XP overrides
• Rate limiting and gamemode filtering

🌾 Farming

Config: farming.yml

• XP for crops, plants, nether crops, vines, cave plants, and more
• Mature-ageable requirement support
• Base-segment protections for vertical plants
• Crop-trample protection support
• Configurable XP per material

🍲 Cooking

Config: cooking.yml

• XP for edible crafting
• XP for furnace/smoker/blast extraction
• XP for campfire cooked-item pickup
• Per-source multipliers
• Interval anti-abuse controls
• Explicit edible item XP tables

🧭 Exploration

Config: exploration.yml

• Background travel XP using scheduled sampling
• Biome discovery XP
• Landmark discovery system
• Per-world biome discovery support
• Anti-flight / anti-glide / anti-vehicle / anti-teleport-farm rules
• Auto-fill support for missing biome entries
• Giant mushroom handling tied into exploration-side config flow

🌿 Foraging

Config: foraging.yml

• Gathering XP from natural vegetation
• Mushrooms, flowers, grass, moss, lichen, vines, azalea, dripleaf, underwater plants, and more
• Right-click harvesting support for berry/vine-style sources
• Natural-only / placed-aware gathering flow
• Configurable XP per material and harvest source

⚒️ Smithing

Config: smithing.yml

• XP for crafting tools, weapons, and armor
• XP for smithing-table upgrades
• XP for smelting extraction of metal outputs
• Strict-list-only item control
• Per-source intervals and rate limits
• Full config-driven item XP tables

📂 Configuration Layout

All generated files are located in:

• plugins/RunestoneSkills/config.yml
• plugins/RunestoneSkills/mining.yml
• plugins/RunestoneSkills/forestry.yml
• plugins/RunestoneSkills/fishing.yml
• plugins/RunestoneSkills/hunting.yml
• plugins/RunestoneSkills/farming.yml
• plugins/RunestoneSkills/cooking.yml
• plugins/RunestoneSkills/exploration.yml
• plugins/RunestoneSkills/foraging.yml
• plugins/RunestoneSkills/smithing.yml
• plugins/RunestoneSkills/oregen_system.yml
• plugins/RunestoneSkills/data.yml
• plugins/RunestoneSkills/exploration_data.yml
• plugins/RunestoneSkills/placed_blocks.yml

What these files do

• config.yml → updater settings and addon-level runtime options
• <skill>.yml → per-skill tuning, enable/disable, anti-abuse, XP values, and messages
• oregen_system.yml → additive custom ore generation config
• data.yml → persistent total XP by player and skill
• exploration_data.yml → discovered landmarks and biomes
• placed_blocks.yml → shared anti-abuse placed-block tracking

Everything is YAML-driven — no recompiling required for normal tuning.

⌨️ Commands

RunestoneSkills currently provides an admin command set plus integration with RunestoneCore’s shared /skills display.

Main commands

• /skills
• /runestoneskills reload
• /runestoneskills installoraxenassets
• /runestoneskills diag
• /runestoneskills orestats
• /rsr
• /rso

Command notes

• /skills → provided by RunestoneCore, but displays enabled skills registered by RunestoneSkills
• /runestoneskills reload → reloads RunestoneSkills configs, listeners, and services
• /runestoneskills installoraxenassets → installs bundled Oraxen assets
• /runestoneskills diag → runs diagnostics for bundled/Oraxen content paths
• /runestoneskills orestats → admin-facing oregen status utility path
• /rsr → shortcut alias for reload
• /rso → shortcut alias for Oraxen asset install

🔐 Permissions

Permission: runestone.skills.admin

• Default: op
• Grants access to:
  • /runestoneskills reload
  • /runestoneskills installoraxenassets
  • /runestoneskills diag
  • /runestoneskills orestats
  • /rsr
  • /rso

Player-facing /skills visibility and related display permissions are handled through RunestoneCore.

🔌 Integrations

• RunestoneCore (required)

  • Skills registry integration
  • Shared profession XP curve
  • Shared API contracts
  • Shared /skills output

• Oraxen (softdepend)

  • Optional mining block XP mappings
  • Bundled asset installer support
  • Custom ore/block content support

🧠 Configuration Philosophy

RunestoneSkills is designed to be:

• config-first
• module-gated
• safe by default
• anti-abuse aware
• performance-conscious
• built for long-term expansion

📚 Documentation

Separate docs in the module include:

• Architecture
• Configuration
• Building
• API
• Forestry / Tree Capitator validation notes

🧯 Support & Reporting

If something looks off, the most helpful info is:

• server version (/version)
• RunestoneCore + RunestoneSkills versions
• the relevant skill YAML section
• the exact console stacktrace (if any)
• clear reproduction steps