Skip to main content

BTC Sky

Skyblock islands with dimensions, coop, research, seasons, events, generators, bank and limits.

Privatev0.1.1World & building
RequiresTypeWriter0.9.0-beta-177 (BTC build)BTC Core (Advanced Slime Paper)Region extensionEntity extensionRoadNetwork extensionBTCMobsProfiles extensionGUI extensionMySql extensionoptionalUiCoreoptionalPacketEventsoptionalMiniPlaceholdersoptional

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

Support

Overview​

BTC Sky is the skyblock engine of the BTC build of TypeWriter. Each player profile owns one island. The island is made of one or more dimensions (Overworld, Nether, End or any custom world you design), each cloned from a template world and configured by a Dimension Template. Every dimension has its own size, upgrades, limits, generator, seasons, events and combat settings.

Players grow their island by buying chunks, upgrades and generator tiers, researching new technologies, filling collections, taking contracts and visiting or fighting other islands. Everything is configured from the web panel: one BTC Sky Main Configuration holds the global rules, one template per dimension holds the gameplay, and a BTC Sky Menu builds the control panel.

BTC Sky is a private extension. It runs on BTC Core (Paper or Folia with Advanced Slime Paper) and is documented here for reference. Other BTC extensions depend on it: Machine uses its islands for placement, limits and research tiers, and FakeBlock can anchor schematics to its dimensions.

Features​

  • Profile-linked islands — one island per profile, created from a dimension template, shared by the owners of a coop profile.
  • Multiple dimensions — unlock and design as many dimensions per island as you want, each with its own progression.
  • Chunk expansion — start with a single chunk and buy more, with a configurable cost curve, custom chunks and a live preview with particle and world borders.
  • Roles and settings — visitor, member, moderator, admin and leader roles, per-dimension permissions and island flags (PvP, fly, mob spawning, explosions, visitor rules).
  • Research tree — branches and nodes unlocked by feeding fragments, loading fuel and waiting for a cooking time.
  • Seasons and events — per-dimension seasons and composable events (meteor showers, storms, mob waves, bosses, treasure rain).
  • Generators and upgrades — tiered cobblestone generators and a data-driven upgrade catalogue.
  • Limits — block, entity, machine and pet limits, plus a mob population budget per dimension.
  • Island bank and contracts — a bank that doubles as the server economy, and player-to-player contracts at a Contracts Table.
  • Collections, ranking, war — global collections with level rewards, a level leaderboard and an island war queue.
  • Hooks for TypeWriter — 38 facts, 33 events, groups, an objective and many actions to build quests around islands.

Installation​

  1. Install the BTC build of TypeWriter with BTC Core. Island worlds are created with Advanced Slime Paper, so the server must provide it.
  2. Install the extensions BTC Sky declares as required: Region, Entity, RoadNetwork and BTCMobs. In practice it also needs the Profiles extension (each island is keyed by a profile id) and the GUI extension (menus).
  3. Optional extensions: MySql (shared storage between servers), UiCore (advanced menus and banners), Party, Friend and Guild for social links, NumericalStorage for currencies, CraftEngine for custom blocks, CustomBiome for custom biomes, and PacketEvents for client-side borders and holograms. MiniPlaceholders is needed for the placeholders.
  4. Put the BTC Sky JAR in plugins/Typewriter/extensions/ and restart the server.
  5. Create one template world per dimension and place it in the slime_worlds folder of the server, under the name you will give to templateWorldName.

How it works​

The instance​

An instance is a placed copy of a game object inside one dimension of one island. BTC Sky has two kinds of instance entries. A BTC Sky Instance spawns an entity (an NPC or a BetterModel model) in a given dimension (targetDimension) at an offset from the dimension's spawn point (spawnOffset), with an optional road network for pathfinding. An Island NPC Instance is the NPC variant whose position is stored per island dimension, so each island has its own copy that the owner can move with the Move Island NPC action.

Dimension templates​

A Dimension Template is the blueprint of one dimension. Add it to the dimensionTemplates list of the main configuration. It defines:

GroupFieldsWhat it controls
IdentitydimensionId, displayName, priority, description, icon, menuSlotsHow the dimension is named and shown in menus.
WorldtemplateWorldName, defaultBiome, allowedBiomes, spawnThe world cloned for each island, biome groups the player can choose from, and the spawn corner.
AccessunlockUnlocked by default or not, primary dimension, cost, required island level, permission, actions fired on unlock.
SizeexpansionInitial and maximum size in chunks per side, cost curve, custom chunks, preview materials.
LimitslimitsBlock, entity, machine and pet limits, and the warp limit.
Populationspawner, mobLevelAtCenter, mobLevelAtEdgeMob spawn rate, distances and caps, and mob level from the centre to the edge.
EconomyblockValues, generator, multipliersIsland level value of each block, generator tiers, crop, drop, spawner and XP multipliers.
PeoplerolePermissions, overrideGlobalFlags, enabledFlagsWhat each role may do in this dimension.
Timeseasons, eventsSeasonal themes and random island events.
ProgressionupgradesThe upgrade catalogue of this dimension.
Combat and crystalcombat, crystal, crystalOffset, crystalMovableWar settings and the stabilisation crystal of the dimension.

The stabilisation crystal has three states (crystal): ACTIVE opens the dimension's control room (and its machine dashboard), DECORATIVE is scenery that refuses interaction, ABSENT forbids placing one.

Islands​

An island belongs to a profile: its id is the profile id. It holds its dimensions, settings, members, upgrades, bank balance, statistics, research progress, collections, warps, holograms, ratings and bans. Islands are saved in the Player Sky Data Artifact, which you reference from the playerSkyDataArtifact field of the main configuration.

An island is created from a template with the Create Island action. By default nothing creates it automatically: set autoProvisionIslandOnProfileCreation to create and enter the primary island right after a profile is created, or keep it off to let a tutorial or a menu unlock the island later.

Island levels are computed by a scanner from the blockValues of each dimension. Stacked blocks count in the level but take a single block of space.

Members, roles and coop​

RoleMeaning
VISITORAnyone who is not a member.
MEMBERA friend of the owner with basic access.
MODERATORCan invite and kick.
ADMINFull management except disbanding.
LEADERThe owner.

The owner assigns roles to friends (members). A high role is a permission level: it does not make the friend a co-owner and does not share progression. What each role may do (BUILD, BREAK, CHEST_ACCESS, INVITE, KICK, BAN, SET_WARP, SET_HOME, SET_BIOME, MANAGE_FLAGS, MANAGE_UPGRADES, TRANSFER, DISBAND…) is set per dimension in rolePermissions of the template.

Coop is different: a coop island has several owners, and they share the island progression (research, collections, level). Coop needs a Coop profile in the Profiles extension. An owner or an island admin invites a player with the Invite Coop Partner action. The invitation expires after 60 seconds and is accepted with Accept Invite or declined with Decline Invite. The Coop Countable Objective doubles its target on coop islands.

Island settings (flags) are toggled per island: IS_OPEN, ALLOW_FLY, IS_PVP_ENABLED, IS_MOB_SPAWNING_ENABLED, IS_EXPLOSIONS_ENABLED, IS_FIRE_SPREAD_ENABLED, VISITOR_ITEM_PICKUP, VISITOR_ITEM_DROP, VISITOR_DOOR_USE, VISITOR_CONTAINER_ACCESS, VISITOR_ANIMAL_INTERACT, BORDER_VISIBLE and WORLD_BORDER.

Upgrades, generators and limits​

Each dimension lists its upgrades. An upgrade has levels with a cost, an effectValue and optional actions on purchase. Its effectType decides what it does: crop growth, mob drops or spawner rate multipliers, potion and island effects, block and entity limit increases, team size, warp limit, generator tier, island fly, event frequency and loot, event unlocks, or a custom effect through actions. If you leave upgrades untouched, the built-in default catalogue is used.

The cobblestone generator has tiers (generator.tiers), each with a cost and a list of rates (a vanilla block or a CraftEngine block id, with a percentage). Leave tiers empty to use the built-in defaults for the overworld, nether and end.

Limits come from the template only: a block or entity type that is not listed is unlimited. Each limit has a base value and can be upgradeable (upgradeCost, upgradeIncrease). Machine and pet limits apply when those extensions are installed. The spawner block adds a mob population budget (maxNearbyMobs, maxPerChunk, per-template caps) so that a farm cannot stop every other spawn. When UiCore is installed, players see a banner when a cap refuses a spawn.

Research​

The research tree is defined in the research section of the main configuration, not in separate entries:

  • Branches (research.branches) are categories with a level curve: the XP needed per level, the points awarded and actions run on level up.
  • Nodes (research.nodes) belong to a branch, sit at an x/y position, and list their parents, powerCost, requiredLevel, criteria, fuels, output, successChance, repeat settings and rewards.
  • Fragments (research.fragments) are items that give power.

A node is researched in steps. The player puts fragments in the node to fill its power, loads one fuel item, the node cooks for the fuel's duration, then the player claims the result. On success the rewards run (each with its own chance) and recipes listed in recipes are unlocked; on failure the failRewards run. Research belongs to the island, so all owners share it, and recipes are given back to each player on join. Other extensions read the unlocked nodes: for example Machine tiers name a research node.

The Research Branch and Research Node manifest entries exist, but the research runtime reads the main configuration, so define your tree there. Use the Research Grant Points, Research Grant XP, Unlock Research and Open Research Menu actions to connect it to your quests.

Seasons​

Seasons are configured per dimension in seasons and are off by default (enabled). Two timing modes exist:

  • FIXED_DURATION — each season lasts fixedDurationHours of real time (168 by default, one week).
  • CALENDAR_LINKED — the year of a TinyEssentials calendar (calendar, startMonth) is divided evenly between the seasons.

Each season definition (definitions, with spring, summer, autumn and winter by default) can override the biome, set a weather pattern (CLEAR, RAIN, THUNDER, SNOW), multiply crop growth, mob spawns, mob drops and XP, show particles, and fire actions at its start and end. The Season Change event reports each change.

Events​

An island event is a composable shell: the Island Event describes when it may run (chancePerCheck, weight, cooldownMinutes, minimumPlayers, conditions, requiredUpgradeId, allowed and blocked dimensions) and lists the mechanics it plays (mechanics). Add the events a dimension may use to events.events of its template; minIntervalMinutes and maxIntervalMinutes space the checks.

Mechanics are separate entries you combine: Meteor Shower, Treasure Rain, Mob Wave, Storm, Eclipse, Boss, Event Ambience (particles and sound), Event Flag, Event Trigger (actions), Temporary Multiplier (XP or drops), Temporary Client Block, Coop Buff and BetterModel Impact. They are listed in the Entries index below.

Economy, contracts and collections​

The island bank holds the island's money. On a server without an economy plugin, the bank is published as the server economy, so a player's money is the money of their island. Deposit and withdraw with the Island Bank Deposit and Island Bank Withdraw actions. Costs in templates use a currency reference (currency) that points to a currency entry such as a NumericalStorage one.

Contracts are agreements between players, taken at a Contracts Table. By default (contractsRequireWorkstation) the menu only opens from the table block (contractsTableBlock, a cartography table by default). Rewards are taxed by contracts.rewardTaxPercent.

Collections track what the island harvests, kills and fishes, per item, with level thresholds (collections.categories). Each level can run actions once (onReach). Players can also unlock or lock a collection with the Unlock Collection action.

War​

When combat.enabled is set on a template, islands of that dimension can take part in wars. An island joins the war queue as an attacker or a defender (from the control panel) and is matched with an island queued in the opposite role. The island must reach combatWar.minIslandLevel, and combatWar.warCooldownMinutes spaces two wars. The template sets the fight itself: core health and regeneration (coreHealth, coreRegeneration), durationMinutes, attackCooldownHours, spawn points and actions for start, victory and defeat. The winner can pillage a share of the loser's bank (combatWar.pillagePercent). Wins, losses and draws are kept in the island statistics.

The Archipel​

The Archipel des Métiers is a shared, read-only world (listed in readOnlyWorlds) of nine islets restored by the island: access, bridges and tiers are stored on the island and exposed as archipel_* facts and actions.

Getting started​

Create a first island with one dimension and let players open the control panel:

  1. In the TypeWriter web panel, open a static page and add a Player Sky Data Artifact.
  2. Add a Dimension Template. Set dimensionId to overworld, templateWorldName to the name of your template world, and keep unlock.isPrimary on. Adjust expansion (initialSizeChunks, maxSizeChunks, baseCost).
  3. Add a BTC Sky Main Configuration. Put the template in dimensionTemplates and the artifact in playerSkyDataArtifact.
  4. Add a BTC Sky Menu with the id control_panel (the Contracts Table opens this entry), build its layoutPool and views, and add a BTC Sky Menu Configuration with the templates of the dynamic lists.
  5. Add a Create Island action with template set to your template, and connect it to a button, a command or a tutorial step.
  6. Publish. Create a profile, trigger the action, and the island appears with its template world.
  7. Test the admin flow with /typewriter island admin search <name> on a staff account.
note

BTC Sky registers its commands under the TypeWriter command. A top-level /island is not defined by the extension: create one with a command entry that triggers the BTC Sky Menu (see Commands).

Commands​

The island commands are registered as @TypewriterCommand, so they live under /typewriter (alias /tw). The menus run them for the player, which is why most of them are internal.

Island commands​

CommandDescription
/typewriter islandOpen the control panel.
/typewriter island visit <islandId>Teleport to an island that is open, unless you are banned.
/typewriter island invite [player]Open the invitation dialog, or invite an online player as a coop partner.
/typewriter island dimension tp <dimId>Teleport to a dimension of your island.
/typewriter island dimension buy <dimId>Unlock a dimension of your island.

The control panel also runs these internal commands: tab and dimension navigation (dim_select, list_scroll, cp, close), expansion (expansion_map, expansion_nav, buy_chunk), level (recalculate_level, recalc_level), warps (warps, warp, warp_create, warp_delete, warp_edit, warp_set_icon, warp_toggle_public), members (members, member_manage, member_promote, member_demote, member_kick), moderation (visitor_kick, visitor_ban, unban), borders (border …), holograms (holograms, create_hologram, edit_hologram), contracts (contracts_browse, contract_apply, contracts_create, contract_accept, contract_reject, contract_cancel and related), upgrades (upgrade, upgrade_confirm, upgrade_generator), research (research_input, research_feed, research_fuel, research_claim), war (declare_war, combat_queue, combat_history, attack), ratings (rate), biomes (biomes, set_biome, set_chunk_biome), settings (toggle_setting, fly_toggle, fly_scope) and ranking (ranking_sort, ranking_dim). They are not meant to be typed by hand.

The chat buttons of a coop invitation run /island coop accept and /island coop deny. These subcommands are not registered by the extension, so connect Accept Invite and Decline Invite to your own commands.

commandAliases of the main configuration (default island, is, islands) only tells the menu system which command words to route to the island tree. It does not register new commands.

Admin commands​

The whole admin branch requires btcsky.admin (or operator status).

CommandDescription
/typewriter island admin search <query>Find islands by id, owner or member name.
/typewriter island admin create <player> <template>Create an island for an online player from a template (by entry id or dimension id).
/typewriter island admin delete <profileId>Delete an island.
/typewriter island admin tp <player or id>Teleport to an island.
/typewriter island admin setlevel <profileId> <level>Set the island level.
/typewriter island admin eco <islandId> get, set <amount>, add <amount>Read, set or add to the island bank.
/typewriter island admin collection <islandId> <collectionId> <level>Set a collection level.
/typewriter island admin upgrade <upgradeId> <level>Set an upgrade level on the island you stand on, in the selected dimension.
/typewriter island admin unlock dimension <islandId> <dimId>Unlock a dimension for an island.
/typewriter island admin event <eventId>Start an island event now on your island.
/typewriter island admin limit show <profileId>Show entity limits next to the real counts.
/typewriter island admin limit budget <profileId> <dimensionId> <value>Set the mob budget of a dimension (unlimited or -1 removes it).
/typewriter island admin limit species <profileId> <dimensionId> <entityType> <value>Set the cap of one entity type.
/typewriter archipel, acces, passerelle <islet>, palier <islet>, ouvrirInspect and grant Archipel access, bridges and tiers (permission btcsky.admin.archipel).

Permissions​

PermissionGrants
btcsky.adminThe whole /typewriter island admin branch.
btcsky.admin.search, .create, .delete, .tp, .setlevel, .eco, .collection, .upgrade, .dimension, .event, .limitEach admin subcommand, as a finer-grained alternative. The parent branch still requires btcsky.admin or operator status.
btcsky.admin.archipelThe /typewriter archipel commands.
btcsky.admin.bypassBypass island protection and warp restrictions, once the player also has the admin bypass flag.
btcsky.admin.dimensionsEnter dimensions that are not unlocked.
btcsky.warp.unlimitedIgnore the warp limit.
btcsky.contracts.bypassOpen contracts without going through the Contracts Table (configurable: contractsBypassPermission).
Permissions of contracts.permissionLimitsRaise the number of open contracts.

The BTC Sky Permission Definitions entry and the permissions and commands sections of the main configuration list many more nodes (btcsky.island.*, btcsky.vip.*, btcsky.command.*). They are documentation: the current code does not check them.

Placeholders​

MiniPlaceholders tags of the btcsky expansion, provided through TypeWriter. A player without an island gets 0 for every tag except has_island. Wherever a dimension is expected, current means the dimension the player stands in, and the default is that dimension when the argument is left out.

Island​

PlaceholderReturns
<btcsky_has_island>true or false.
<btcsky_context_state>State of the profile and island link (NO_PROFILE when none).
<btcsky_island_id>Island (profile) id.
<btcsky_island_owner>, <btcsky_owner_name>Owner name.
<btcsky_island_role>Role of the player on the island.
<btcsky_island_level>, <btcsky_level>Island level.
<btcsky_island_balance>, <btcsky_bank_balance>Bank balance.
<btcsky_island_members_count>, <btcsky_member_count>Number of members.
<btcsky_island_members_online>Members online.
<btcsky_member_max>Team size limit including upgrades.
<btcsky_team_members_list>Comma-separated member names.
<btcsky_is_coop_island>true for a coop island.
<btcsky_island_creation_date>Creation date (yyyy-MM-dd HH:mm:ss).
<btcsky_island_worth>Sum of the dimension levels.
<btcsky_visitor_count>Visitors currently on the island.
<btcsky_biome_current>Name of the biome under the player.
<btcsky_season>Season of the current dimension, or of the calendar date outside an island.
<btcsky_setting:name>Coloured on/off state of a setting: visit (or open), fly, pvp, mobs, explosions, fire, world_border, possession_border.

<btcsky_island_exp> always returns 0, <btcsky_island_level_progress> always 100 and <btcsky_bank_interest_rate> always 0.0: they exist for compatibility only.

Size, biomes and counts​

PlaceholderReturns
<btcsky_size>Unlocked chunks in the current dimension.
<btcsky_island_size>Unlocked chunks in all dimensions.
<btcsky_size_max>, <btcsky_max_size>Maximum chunks of the current dimension, from its template.
<btcsky_island_size_max>, <btcsky_island_max_size>Maximum chunks over all dimensions.
<btcsky_biomes_acquired>, <btcsky_island_biomes_total>Unlocked biomes over all dimensions.
<btcsky_biomes_total>Biomes that can exist over all dimensions.
<btcsky_biomes:group>Unlocked biomes of a biome group in the current dimension.
<btcsky_island_biomes:group>Unlocked biomes of a biome group over all dimensions.
<btcsky_block_count:MATERIAL>Count of a block in the current dimension.
<btcsky_upgrade_level:id>Level of an upgrade in the current dimension.
<btcsky_upgrades_acquired>, <btcsky_upgrades_total>Upgrades bought, and upgrades available, over all dimensions.
<btcsky_warp_count>, <btcsky_warp_list>Number and names of warps.
<btcsky_warp_limit>Default warp limit from the configuration.

Progression and social​

PlaceholderReturns
<btcsky_contract_completed_count>Contracts completed.
<btcsky_research_unlocked_nodes>, <btcsky_research_unlocked_count>Research nodes unlocked.
<btcsky_research_points>Research points.
<btcsky_collection_total_unlocked>Collections unlocked.
<btcsky_collection_progress:id>Amount collected for a collection id.
<btcsky_ban_count>Banned players.
<btcsky_rating>, <btcsky_rating_count>Average rating (1 decimal) and number of votes.
<btcsky_combat_wins>, <btcsky_combat_losses>, <btcsky_combat_draws>, <btcsky_combat_winrate>War statistics and win rate in percent.

Dimensions​

The argument is a dimension id or current.

PlaceholderReturns
<btcsky_dimension_id:dim>, <btcsky_dimension_display:dim>Dimension id, and its capitalised display name.
<btcsky_dimension_unlocked:dim>, <btcsky_dimension_is_locked:dim>true or false.
<btcsky_dimension_level:dim>Dimension level.
<btcsky_dimension_generator_tier:dim>Generator tier.
<btcsky_dimension_event_next:dim>Time to the next event (mm:ss), Now or Unknown.
<btcsky_dimension_size:dim>, <btcsky_dimension_size_max:dim>Unlocked chunks and maximum chunks.
<btcsky_dimension_biomes_total:dim>Unlocked biomes.
<btcsky_dimension_upgrades_acquired:dim>, <btcsky_dimension_upgrades_total:dim>Upgrades bought and available.
<btcsky_dimension_visitor_count:dim>Visitors in the dimension.
<btcsky_dimension_upgrade_level:dim:id>Level of an upgrade in the dimension.
<btcsky_dimension_biomes:dim:group>Unlocked biomes of a group in the dimension.
<btcsky_block_limit:dim:MATERIAL>Block limit in the dimension.
<btcsky_dimension_lock_mark:dim>[X] when the dimension is locked, empty when open.
<btcsky_dimension_locked_palette:dim>Palette name for a locked or open dimension, for menu buttons.

The control panel is a single menu with views.

  • BTC Sky Menu holds the layoutPool, the views (one per screen), the defaultViewId and the inventoryRows. Tab slots carry the tag view:<viewId>; frames with variable content use the layout id @view. A view is opened with <viewId> or <viewId>:<argument> (for example collection_detail:mining).
  • Content items use a buttonType of the form btcsky_button:TYPE. The extension fills the live data (island info, dimensions, upgrades, collections, ranking, warps, contracts, members, bans, research, expansion chunks, borders, combat, holograms…) and attaches the clicks.
  • BTC Sky Menu Configuration holds the item templates of the dynamic lists.
  • Open Specific Menu opens a given view, and Open Friends Menu opens the friends screen.

The panel is a catalogue when opened from the global menu (you browse, you buy nothing). Opened from a stabilisation crystal it becomes the dimension's control room, and buying upgrades and chunks is allowed; the purchase commands refuse otherwise.

When UiCore is installed, BTC Sky also publishes lists (upgrades, expansion map, visits, collections, ranking, members and borders) to UiCore menus, and shows banners when a population cap refuses a spawn.

Entries​

161 entries, generated from the extension source.

Actions61
Events33
Objectives1
Facts38
Entities1
Activities1
Groups2
Artifacts1
Manifests20
Definitions1
Other entries2

Troubleshooting​

The island world is not created. Each dimension clones the world named in templateWorldName from the slime_worlds folder. The file must exist and BTC Core must provide Advanced Slime Paper. Check the server log for the dimension id and the island id.

A player has no island after creating a profile. autoProvisionIslandOnProfileCreation is off by default. Trigger a Create Island action, or turn the option on.

/island does not exist. The extension only registers /typewriter island. Create your own command that triggers the BTC Sky Menu, and note that the menu entry opened by the Contracts Table must have the id control_panel.

Contracts refuse to open. With contractsRequireWorkstation on, contracts only open from the Contracts Table (contractsTableEnabled and contractsTableBlock). Turn it off for a test server or give the bypass permission.

Every placeholder returns 0. The player has no island or no active profile. Check <btcsky_has_island> and <btcsky_context_state>. A dimension argument must be a valid dimension id or current.

My research tree does not appear. The research runtime reads research.branches and research.nodes of the main configuration. Research Branch and Research Node entries are not read.

Seasons or events never start. Seasons are disabled by default (seasons.enabled). Events need at least one event in events.events of the template, and an event only fires when its conditions, requiredUpgradeId and minimumPlayers match.

No mobs spawn on the island. Check spawner.enabled, maxNearbyMobs and maxPerChunk, and the island flag IS_MOB_SPAWNING_ENABLED. Use /typewriter island admin limit show <profileId> to compare the counters with the real number of mobs.

Players cannot build in a shared world. Worlds listed in readOnlyWorlds (default archipel_metiers) are protected for everyone, except holders of machine.protection.bypass.

  • Machine — machines placed on islands, with island limits and research tiers.
  • FakeBlock — schematics anchored to island dimensions.