Skip to main content

RPG Core

Stats, equipment bonuses, professions, items, backpack, auction house, trade and movement.

Privatev0.1.1RPG & progression
RequiresTypeWriter0.9.0-beta-177 (BTC build)GUIVaultUiCoreoptionalBTCMobsoptionalProfilesoptionalPartyoptional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview​

RPG Core is the progression layer of a BTC server. It is one large extension (built under the name RPGBundle) that groups the stat system, a custom item catalogue with sets and gems, professions with levels, a global level, backpacks and wardrobe, an auction house, secure player trade, custom crafting stations, custom fishing, movement abilities (crawl, vault, climb) and Ether corruption zones.

Almost everything is configured in one entry, RPG Core Configuration, which has one section per system. The other entries are small building blocks: actions to give items or change stats, facts to read them, menus to open, and artifacts to store player data.

The core idea is the stat model described below: every player has numeric stats (strength, health, crit chance, speed...), equipment adds to them, and the result drives combat, gathering and vanilla attributes.

Features​

  • Stat model — 77 stats with a base value per player, bonuses from equipped items and named constraints.
  • Item catalogue — categories of custom items with stats, rarity, level requirements and equipment sets with set bonuses.
  • Professions — levels, XP curves, level rewards (permanent stats and triggers), boosts, competitions and a profession menu.
  • Global level — a weighted level computed from professions and quests, used to gate movement abilities and more.
  • Storage — personal backpacks and a wardrobe (accessories and elytras) saved in artifacts.
  • Economy — an auction house and a secure player-to-player trade with a rolling 24-hour currency limit.
  • Crafting — custom recipes, anvil, grindstone, loom, alchemy, composter, cartography and workstations with level gates.
  • Movement — crawl with a double sneak, automatic vault and wall climb, with optional BetterModel animations.
  • Corruption — zones of Ether corruption that spread, can be purified and spawn corrupted mobs.
  • Commands — admin tools for stats, professions, items, boosts and inventories, plus player commands for auction, trade, recycling and unstick.

Installation​

  1. Install the GUI extension: menus (professions, backpack, wardrobe, auction, trade) are rendered with it.
  2. Install a Vault-compatible economy plugin (Vault) if you use the auction house or trade with the default economy.
  3. Optionally install UiCore (menus and progression HUD), BTCMobs (corrupted mobs, mob groups), Profiles, Party and BTC Sky for the integrations that read them.
  4. Put the RPG Core JAR in plugins/Typewriter/extensions/ and restart the server.

Getting started​

  1. In the TypeWriter web panel, open a static page and add a Player State artifact: it stores each player's base stats and effects.
  2. Add a Profession Data artifact if you use professions.
  3. Add the RPG Core Configuration entry. In stats, set artifact to the Player State artifact. Leave stats.stats empty to load the built-in defaults, or add items to override the display name, default, minValue, maxValue or displayFormat of a stat. In professions, set artifact to the Profession Data artifact and add a profession.
  4. In items, add a category and a catalogue item with stats such as STRENGTH and HEALTH and a rarity.
  5. Publish. Give yourself the item with /rpgitem give, wear it, and check the value with /rpgstat info <player> STRENGTH.
  6. Trigger actions such as Give BTC Item, Add Stat or Profession Grant XP from quests and NPCs.
One configuration entry

Create a single RPG Core Configuration entry and keep one source of truth for all sections.

How it works​

The stat model has four layers.

  1. Definition. Every stat is a fixed identifier (STRENGTH, HEALTH, CRIT_CHANCE, SPEED, MINING_EFFICIENCY...). Each has a scope (PLAYER: only the player's base stat can hold it; ITEM: only equipment bonuses; BOTH) and a unit that says how it is stored: absolute vanilla units (health points, armor), a percent of the vanilla base (speed, 100 = vanilla), a fraction from 0 to 1 (crit chance, resistances), a multiplier where 1 is neutral, additive percentage points, or plain points. The unit is intrinsic to the stat; the configuration cannot change it.
  2. Base value. Each player has a persistent base value per stat, starting at the stat's defaultValue, saved in the Player State artifact. It changes through Add Stat, Remove Stat, profession level rewards (stats) and /rpgstat. It is rounded to 2 decimals (integers for INTEGER stats) and clamped between minValue and maxValue.
  3. Equipment bonuses. Whenever the equipment changes, the extension recomputes the bonuses of the helmet, chestplate, leggings, boots, main hand, off hand and the active wardrobe page. For each worn item it adds the stats from its catalogue definition, the stat component stored on the item, and vanilla enchantments mapped to stats. Items whose profession-level requirements are not met give nothing. Stats with scope PLAYER ignore equipment. These bonuses are temporary and never saved.
  4. Constraints. Constrain Stat holds a stat between a min and a max under a named source until Release Stat Constraint lifts it: a duel arena that caps attack, a cursed hall that lowers defence. Several constraints tighten each other (highest floor, lowest ceiling; the ceiling wins on conflict).

The total value is base + equipment, clamped, then constrained. Stats that match a vanilla attribute (health, armor, speed, attack damage, jump strength, reach...) are pushed to that attribute with the unit conversion; the others are read by the code that needs them: crit chance and damage, lifesteal, dodge, block, double drops, mining and woodcutting efficiency, fishing strength, profession XP boost and so on.

Temporary Stat adds a stat for a duration (potions, buffs). Read a stat in a condition with Player Stat, which returns the value multiplied by scale and rounded.

Configuration​

Everything below is a section of RPG Core Configuration.

SectionWhat it configures
itemsItem catalogue (categories, items, rarity, requirements), equipment sets and gems.
statsThe Player State artifact, per-stat overrides, global options (regeneration, crit, lifesteal, efficiency, mob groups, bonus loot) and command messages.
professionsThe profession list, levels, XP curve and rewards, the profession menu and messages.
inventoryBackpack and wardrobe layouts and storage.
auctionAuction house taxes, durations, economy and menus.
tradeSecure trade: distance, request lifetime, stack limit, 24-hour currency limit, ledger artifact, economy and menu.
movementCrawl, vault and climb tiers, global level gates, BetterModel animations.
crafting, specialRecipes, anvil, enchantment, alchemy, grindstone, loom, cartography, cartographyCrafting, composter, workstations, industrialRecipes and custom workstations, each gated by levels or delays.
fishing, gathering, mobTrapCustom fishing (including lava and void), unified resource gathering (XP, loot, gating) and mob capture.
boosts, globalLevel, respawn, recycling, divers, beaconTemporary boosts, the global level formula, conditional respawn, recycling, resin and the island beacon.
etherCorruptionEther corruption zones.
combatFeedback, vanillaTooltipDamage numbers, health bars and hidden vanilla tooltips.

Commands​

All commands are registered at startup with their aliases. Admin commands need borntocraft.rpg.admin.

Command (aliases)PermissionDescription
/rpgstat (statadmin, btcstat)borntocraft.rpg.adminlist, info <player> <stat>, set, add, remove <player> <stat> <value>, reset <player> <stat>. Stats with scope ITEM cannot be changed directly.
/rpgadmin (rpgadm)borntocraft.rpg.adminstat <player> <stat> <get|set|reset> [value], profession <player> <profession> <get|setlevel|reset> [value], boost <player> <stat> <amount> <seconds>, corruption <create|remove|list>, mana <player> <set|give|get>, reload (reapplies stats of online players), debug <player>.
/rpgprofession (profes, prof)borntocraft.rpg.adminaddxp, removexp, setxp, addlevel, setlevel, reset, info, list, menu.
/rpgitem (btcitem, customitem)borntocraft.rpg.admingive, remove, list, info, menu.
/rpgcraft (craftadmin, btccraft)borntocraft.rpg.adminlist, inspect, preview, menu for recipes.
/rpginventory (btcinv, inventoryadmin)borntocraft.rpg.adminbackpack <list|open|reset>, wardrobe <open|info>, list.
/rpgboost (boost, xpboost)borntocraft.rpg.admingive, clear, list profession XP boosts.
/questrewardreset (qrr, resetquestreward)btc.admin.questrewardreset<menuId> <player|all>: resets claims of a Quest Reward Menu.
/rpgauction (ah, auction)nonebrowse, management, sellmenu, collection, list <price> <minutes> [buyout], bid <id> <amount>, buy <id>, cancel <id>, claim, finalize (admin).
/rpgtrade (trade, p2ptrade)none<player> opens a request; accept <id>, deny <id>, money <amount>, confirm, cancel.
/rpgrecycling (recycling, recycle)noneOpens the recycling menu.
/unstick (rollback)noneTriggers the entry whose id is action:system_unstick; it answers with an error if that entry does not exist.

Permissions​

PermissionGrants
borntocraft.rpg.adminAll admin commands above.
btc.admin.questrewardreset/questrewardreset.

Placeholders​

RPG Core registers the MiniPlaceholders expansion btc. See Placeholders for the full list.

Entries​

42 entries, generated from the extension source.

Actions24
Events4
Facts6
Audiences1
Artifacts6
Manifests1
  • BTC Rpgcore ConfigurationConfigure BornToCraft RPG core systems (Items, Stats, Professions, Inventory, Crafting, Commands, Fishing, Auction, Movement, Trade)

Troubleshooting​

No btc_rpgcore_configuration entry found! Create one in TypeWriter UI. Nothing is loaded without the configuration entry. Add one and publish.

Stats reset or are not saved. stats.artifact is empty or points to a missing artifact: base stats are then only held in memory. Link a Player State artifact. The same applies to professions.artifact for profession progress.

An item gives no stats. Check the stat id (aliases such as ATTACK_DAMAGE or MAX_HEALTH are accepted), that the item is worn in an armor, hand or active wardrobe slot, that the player meets its profession requirements, and that the stat scope is not PLAYER. A stat listed in the configuration with a displayFormat must contain {value}, and a minValue must not exceed maxValue, or the configuration fails to load.

percentageMultiplier must be ... at load. For stats whose unit is fixed (for example fractions and multipliers use 100, percent-of-vanilla stats use 1), the display multiplier is checked. Remove the override or use the value in the error.

/rpgstat set refuses a stat. It says the stat is item-only: its scope is ITEM, so only equipment can hold it. Use an item or a temporary stat.

/unstick says the action is not configured. Create a triggerable entry with the id action:system_unstick.

The auction house or trade cannot move money. The default economy is Vault: install Vault and an economy provider, or configure the economy adapter of the section.

  • UiCore — renders the progression, wardrobe and storage panels.
  • Profiles and Party — profile switching and party XP sharing.
  • BTC Sky — island-aware mechanics.