Getting Started
Why Shogi exists
Minecraft mod configs go through a lot of churn: they often start simple, and then keep growing and changing as new feature requests come in. Customizability is what makes modding great, but it also makes it more complicated.
A teleport cost may need to depend on distance, dimension, item used, or whether the player is on cooldown. Falling through the void may need different behavior per dimension. Reviving a downed player may need to check whether monsters are nearby before allowing another player to help.
Without Shogi, each of those mods has to keep adding more purpose-built configuration options for each of those cases. That leads to config creep: larger files, more special-case implementations, and still not enough flexibility for the next player's wild imagination.
Shogi takes that complexity and moves it into a shared rule layer. Mods expose selected values or actions to Shogi, and players or modpack authors can override them with contextual rules when they need more control.
What Shogi does
Shogi is a library mod used by Minecraft mods like Waystones to allow for rule-based contextual configuration of properties and events.
A supported mod defines a named Shogi value, such as waystones:warp_stone_use_time, and instead of merely being a numeric option, it enables the full Shogi effect library to turn it into a dynamic rule.
This opens a lot of new possibilities without clogging up the config file:
- Having it take longer while in the Nether
- Having it take longer while monsters are nearby
- Having it take longer the more damaged the warp stone is, etc.
But this can go beyond just numeric values too. Mods can use Shogi to define hooks and cost evaluations as well. Waystones uses this for its "Warp Requirements", which defines both whether a warp is allowed as all, as well as all the costs associated with it.
Rules then describe how those contexts should be resolved. For example, in Hardcore Revival you can use a Shogi rule to block revival in the Nether or add an item cost, xp cost, cooldown, etc. - all without needing to think of every possible use case up front, through a single rule instead of a conglomerate of config options.
is_dimension('minecraft:the_nether') -> refuse('You cannot revive others in the Nether.')
is_dimension('minecraft:the_nether') -> item_cost('golden_apple')
This guide is for players and modpack developers who want to customize mods that expose Shogi properties. It is recommended to also consult the mod-specific guides, such as the Warp Rules page in the Waystones documentation.
Shogi can be used by any mod developer to provide easy extensibility for their configuration. For information on how to use Shogi when developing your own mods, see the Developer Guide.
Prerequisites
You must install the Shogi mod to configure rules for supported mods. Some mods (like Waystones) already have Shogi marked as required dependency, while others only offer optional Shogi support.
If not already installed, download and install Shogi like you would any other mod.
Rule Configuration File
The location where rules can be defined differs depending on the support mod. Consult the other mod's documentation to find out where rules should be configured.
If not otherwise specified, the file for configuring rules is usually <modid>.rules.json. If that doesn't work, try shogi.rules.json or refer to the mod's documentation.
Example: Waystones
Waystones exposes Shogi values in a config/waystones.rules.json file (create it if it does not exist).
{
"waystones:warp_stone_use_time": [
"32",
"is_dimension('minecraft:the_nether') -> 16"
],
"waystones:scroll_use_time": [
"32",
"is_dimension('minecraft:the_end') -> 48",
"is_portal_scroll -> '1s'"
]
}
This sets a default at 32 ticks, with overrides for a shorter warp stone use time in the Nether, makes scrolls take longer in the End, and makes portal scrolls always take one second (20 ticks).
Basic Rule Syntax
Shogi rules follow a simple pattern:
condition -> effect
Some conditions and effects take parameters:
is_dimension('minecraft:the_end') -> refuse('You cannot use Waystones in the End.')
Note that effects are evaluated in context of the property they are configured for. For example, when the above rule is configured as part of Waystones' warpRequirements option, is_dimension in this case would refer to the player's dimension, and refuse would determine that a teleport is not allowed.
Multiple parameters are separated by commas, and conditions can be negated with an exclamation mark:
!is_block_state_property('origin', 'player') -> refuse('You cannot break generated Waystones')
Again, rules are context-specific, and this example assumes it's defined as part of an Unbreakables rule. In that case, is_block_state_property refers to the block being broken, and refuse determines that the block will be unbreakable with the given error message.
Conditions can be composed using plus, comma or contextual modifiers
is_biome('minecraft:forest') + can_see_sky -> refuse('You can't break forest blocks that can see the sky')
has_mob_effect('minecraft:poison'), has_mob_effect('minecraft:wither') -> refuse('You can't do this while under the effects of Poison or Wither')
offhand(is_item('minecraft:totem_of_undying')) -> refuse('You can't teleport while holding a Totem of Undying')
For a full list of all inbuilt conditions and effects, check the Available Effects page. Mods like Waystones may also provide additional conditions and effects that can be used; refer to the mod-specific guides for a list of those.