Crate yog_api

Expand description

Yog API — the single crate mod authors depend on.

A facade that re-exports every Yog domain plus the central Registry hub. Add a new domain crate, re-export it here, and mods pick it up via yog_api::*. Items are available both flat (yog_api::Registry) and namespaced by domain (yog_api::world::World).

Re-exports§

pub use java::mod_loaded;
pub use yog_data;
pub use yog_ids;
pub use yog_sync as sync;
pub use ctor;

Modules§

advancements: Advancements: a mod’s are content (.ydef kind: "advancement"); one granted by the mod’s code says so (criteria: [{ granted: true }]) and is awarded here. What a player has is asked here too, and on the client by crate::client::advancement_done.
block: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. What happens to blocks.
body: Bodies, camera and movement (yog-body, see its docs): pose and dress entities, disguise and morph them, move the camera, replace the local player’s travel step. Register handlers with Registry::on_body, Registry::on_camera and Registry::on_travel; say which entities to ask about with track and track_type.
book: Guide books: the .ybook format and its renderer.
bossbar: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Boss bars: the host’s actions.
chat: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Messages to players: the host’s actions.
client: Client-side helpers (ABI minor 1): opening a screen with flags, sounds only the local player hears, the local player’s held items and the keyboard state. All are no-ops (or None/false) on a dedicated server and before the mod registered.
command: Commands.
config: Mod configuration (typed key/value files).
content: Content registration (custom items / blocks / food).
core: Core types and handles.
dimension: Custom dimensions — dimension-type definitions and runtime chunk generation.
entities: Mod entities the loader draws: a type registered with a model gets its body model, playing the clip of its state — walk while it walks, else idle, or the state in its entity data yog:state (a string the mod sets on the server) — timed by the world’s clock, alike for everyone.
entity: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. What happens to entities.
entity_flags: What kind of entity something is, as a bit set (EntityInfo::flags).
event: Events by plane — event::player::session::Join, event::block::Break, … — subscribed with Registry::on / before / after.
game: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. The game: the host’s actions.
gfx_core: Core graphics constants and enumerations.
gfx_draw2d: 2D drawing helpers — thin wrappers over the draw2d_* ABI functions.
gfx_gl: Low-level GPU resource wrappers: Buffer, VertexArray, ShaderProgram, Texture.
gfx_image: Yog image sources — the names every Yog API that shows a picture takes instead of raw Minecraft resource paths, so mods don’t depend on the game version, the loader or where Mojang keeps a texture this release.
inventory: Inventory framework — real Container/Menu screens (BlockEntity-backed), as opposed to ui’s HUD-drawn overlays. See yog-inventory’s DESIGN.md.
item: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Items’ services: what a mod says about its items’ stacks.
java: Other mods — Yog’s and Java ones — from a Yog mod: whether one is loaded (crate::mod_loaded), and calls into a Java mod’s API by reflection (call).
loot: Loot: change what loot tables give — a chest’s, a block’s drops, a mob’s. crate::Registry::change with yog_event::world::loot::Roll sees every table rolled; a LootModifier (a .ydef, or built in code) adds and scales items on some tables, finishing the stacks it adds with the mod’s named loot functions (crate::Registry::loot_function).
mirror: Mirrors (docs/design/bus.md, “Mirrors”): data read every tick kept in shared memory. A mod declares the fields it reads (Declared: read in place, released on drop) or provides a mirror (Registry::provide_mirror: its writer is called when fields are due, with only those). Usually through #[yog_mirror], which generates both sides typed.
net: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Sending over the network: the host’s actions.
network: Networking (raw-byte packets over channels).
particle: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Particles: the host’s actions.
player: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. What players do.
scoreboard: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. The scoreboard: the host’s actions.
sound: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Sounds: the host’s actions.
storage: Where the mod keeps its data (typed stores by scope, values kept with the world). Where the mod keeps its data — typed values in stores scoped the way web storage is (yog-storage), opened for this mod in the right folder:
tag: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. Tags: the host’s actions.
ui: UI framework — flexbox layout + widgets on top of yog-gfx.
vanilla: The game’s ids as constants (yog_api::vanilla::items::REDSTONE), so mod code names them instead of spelling them. Generated by yog-cli/src/vanilla/gen_api.py from the supported versions (1.20.1, 1.21.1); one missing from a version says so. Don’t edit — rerun the script.
widget: Widget types and styling.
world: The bus’s domains: each one’s actions as functions (world::get_block(dim, pos), entity::position(uuid), player::give_item(name, item, count)) beside its events. What happens to the world.

Macros§

content: Pulls the mod’s blocks and items — content/**/*.yblock and *.yitem, made in Yog-IDLE’s model editor — in as module content, and registers them (every file without "register": "manual") right after Mod::register:
error: Logging macros (yog_api::info!, warn!, error!). Log at ERROR level.
export_mod: Export a Mod as a dynamically loadable Yog mod.
import: Inter-mod communication proc-macros. Another mod’s exports, callable here: import! { from "mod_id" { pub fn name(a: A) -> R; pub struct T { .. } } } — each fn calls mod_id:name on the bus and answers Option<R> (None: the mod isn’t loaded, or it failed); each type gets the schema its values cross with.
info: Logging macros (yog_api::info!, warn!, error!). Log at INFO level.
resources: Pulls the mod’s .yres resources in as module res — one type per resource set, with an accessor per entry:
tr: tr!("key") = tr("key"); tr!("key", a, b) fills the text’s %s specifiers with a and b (anything Display) — see format_translation.
ui_component: Registers .yui components (types implementing ui::component::Component) when the mod’s library loads, so screens can use <Name …/> and Yog-IDLE’s designer host can draw them. The code yog build generates from a <Component> .yui calls this — mods don’t write it themselves.
ui_components: Compiles in the mod’s component .yui files that have no code-behind .rs (those with one are pulled in by its ui_include!) — call it once, in src/lib.rs:
ui_include: Pulls a .yui screen’s generated code into the current module — the code-behind’s half of src/<name>.yui:
warn: Logging macros (yog_api::info!, warn!, error!). Log at WARN level.

Structs§

ArmorDefense: Defense points per armor piece.
ArmorMaterial: What armor is made of. The game’s are built in (ArmorMaterial::built_ins); a mod declares its own in a .ydef (kind: "armor_material") or registers one.
ArmorPiece: An item as a piece of armor.
BlockDef: A custom block to register; it also gets a matching block-item.
BlockHit: A block a ray stopped at.
BlockInfo: A block’s properties (block::Info).
BlockPos: A block position in the world.
BlockProperty: A property of a block’s own: its name and values (the first the default; false, true is a yes/no).
Book: A guide book: what a .ybook file holds.
BookCategory: A category of the book’s home page.
BookEntry: One entry: its pages, in a category.
BookRenderer: A book being read: what it shows, laid out for the screen it was last drawn on.
ClientPacketEvent: A packet the server or the client received (on_packet / on_client_packet). A packet the server sent on a mod’s channel; keyed by the channel.
CommandContext: Details of a command invocation.
Config: A key/value configuration file backed by <game_dir>/yog-config/<mod_id>.cfg.
Entity: An entity, by its uuid: every action whose first field is uuid.
EntityDef: An entity type to register (.yentity). Its look is a body model (model, .ymodel) with clips by state; what it does beyond goals is the mod’s code (entity events, a tick of its own).
EntityInfo: A loaded entity (entity::Info).
EventCx: What a handler is handed besides the event: when it runs.
FoodDef: Nutritional properties for a food item.
GeneratedChunk: A chunk column a generator fills (the world/generation/chunk event, keyed by generator): where it is, and every block placed so far — a palette and a cell per block, like the game’s chunk sections, so the host sets them a section at a time. Several handlers fill one column in turn (terrain, then a mod’s ores).
GfxContext: Handle to the GPU and draw capabilities for a single render frame.
InventoryDef: Describes one inventory-backed screen: how many slots a mod block has, where they sit, whether the player’s own inventory is appended below, and which background texture to draw (vanilla default, or a mod’s own).
ItemDef: A custom item to register, identified by namespace:path.
LayoutNode
ModInfo: An installed mod.
PacketEvent: A packet the server or the client received (on_packet / on_client_packet). A packet a client sent on a mod’s channel; keyed by the channel.
PlacedBlock: A block found in the world: where, and its state.
Player: An online player, by name: every action whose first field is player.
PlayerInfo: An online player’s state (player::Info).
Point: A point in a world (blocks, fractional).
Recipe: A recipe, in Yog’s own format — what a .yrecipe says. The host writes the recipe JSON of its Minecraft version from it.
Rect: A rectangle: its corner x, y (the one with the smallest coordinates) and its size.
Registry
Rotation: Which way an entity faces, in degrees.
ScreenSlot: A slot of an open inventory screen: what it holds, where it’s drawn (GUI pixels from the screen’s corner).
SlotLayout: Pixel position of a single slot in vanilla GUI coordinate space (the same space vanilla screens use: origin at the panel’s top-left corner, one vanilla slot = 18×18px).
SlotStack: A stack in an inventory slot.
SoundGroup: What a block sounds like: the sound events it plays when broken, stepped on, placed, hit while mining and fallen on. The game’s groups are built in (SoundGroup::built_in); a mod registers its own (Registry::register_sound_group, or a .ydef of kind sound_group) and names it in BlockDef::sound.
Stack: A stack of items: what it is, how many, its data (SNBT).
StartupGrant: Grant items/books to every player once when they first join. This is the Yog-side replacement for grant_patchi_book.json.
ToolItem: An item as a tool or weapon.
ToolMaterial: What tools are made of. The game’s are built in (ToolMaterial::built_ins); a mod declares its own in a .ydef (kind: "tool_material") or registers one (Registry::register_tool_material).
UiRoot: Top-level UI tree. Build it, call layout, then [render] each frame.
World: A dimension (minecraft:overworld): every action whose first field is dim.
YogApi: Stable C ABI — re-exported so mods don’t need a direct yog-abi dependency. Passed to yog_mod_register: the bus — everything a mod does goes through it (docs/design/bus.md) — and the one thing that can’t afford a message, the frame’s graphics.
YogDimensionDef: A dimension definition — what a mod registers to create a custom dimension, or to patch an existing (including vanilla) one. Sent as Yog Data via Registry::register_dimension (in yog-api); the host registers (or patches) a LevelStem/DimensionType entry from it at mod-init time.
YogDimensionTypeDef: Properties of a dimension type — mirrors Java’s YogDimensionType.

Enums§

Align
ArmorSlot: Where a piece of armor, or something else worn, is worn.
BookPage: One page of an entry: {"type": "spotlight", "item": "@item:minecraft:stick", …}.
Cooking: How a cooking recipe cooks.
Dock: WinForms-style dock — which edge(s) the widget attaches to inside its parent.
EntityKind: What kind of entity a type is.
EventPhase: Whether a handler is running before or after the action.
Face: The six block faces, in Minecraft’s Direction order, named as yog_ids::direction names them (a test holds them to it).
Facing: Which ways a block can turn.
FlexDir
Flow: What a handler decides about an event.
FocusStyle: How a focused widget shows its focus indicator.
Placement: Which way a block turns when placed.
RecipeKind: What a recipe is made of besides its result.
Stretch: How an image fills the box it’s given — WPF’s Stretch.
Units: A size value — either a fixed pixel amount, a CSS-style percentage of the parent’s own resolved content size (0.0–100.0), or Auto (size to content/available space, this crate’s original behaviour).

Constants§

ABI_VERSION: Stable C ABI — re-exported so mods don’t need a direct yog-abi dependency. ABI_MAJOR * 10_000 + ABI_MINOR. Checked at mod load time.

Traits§

Event: An event the bus carries; its payload is Self in yog-data’s binary form.
IntoFlow: What a handler may return: nothing (Continue), whether to let it happen (false cancels), or a Flow.
Message: A message the bus carries; its payload is Self as a frame (yog_data::frame: packed by position — both sides have the schema).
Mod: Implemented by every Yog mod. Called once at startup to register handlers.
Packet: A packet’s payload as bytes and back — every Schema type is one.
Schema: #[derive(Schema)]: a type read and written as Yog Data (stores, packets, frames). A Yog Data format.
Service: A call the bus carries: its payload is Self, its answer a Service::Reply.
UiHandled: What a Registry::register_ui handler returns: () (never marks events as used) or bool (true = the handler used this key:/char: event — the host then doesn’t, e.g. Esc doesn’t close the screen).

Functions§

call: Calls request’s provider: its answer, None when no one answers (a service not on this host, or this mod not registered yet).
call_export: Calls mod mod_id’s export name with args: its answer, None when it isn’t there (the mod isn’t loaded) or failed.
close_ui: Close the Yog UI screen showing ui_id — e.g. from that screen’s own “Done” button. Does nothing when another screen is open. Deferred onto the render thread, so the handler that calls it finishes first. Client side; a no-op on dedicated servers.
emit: Emits event on the bus — a mod’s own event, or the game’s on its behalf; whether no handler cancelled it (before the event, where it can be).
export_address: Where mod mod_id’s export name is provided: mod_id:name.
format_translation: Fills Minecraft-style format specifiers in pattern (what lang files use): %s/%d take the next argument, %1$s/%2$d a numbered one (from 1), %% is a literal %. A specifier without an argument stays as written.
installed_mods: All installed mods known to the loader: .yog mods plus, where the host exposes them, platform (Java) mods. Callable at any time after this mod’s register() ran — including client-side UI handlers. Note that during register() mods that load after this one are not in the list yet; query lazily (e.g. on first render) for a complete view.
mod_id: This mod’s id (its manifest’s), once the runtime has loaded it.
open_ui: Open the Yog UI registered as ui_id (client side; no-op on dedicated servers). modal blocks game input, pause pauses singleplayer. Callable from any handler after registration — e.g. an on_client_packet handler.
split_state: A block state ("ns:id[k=v,...]") as its id and its properties.
tag_name: A tag’s name in the player’s language — kind the content’s (item, block, entity, fluid, biome), id the tag’s (yog:ingots/iron): the translation recipe viewers show (tag.item.yog.ingots.iron), else the id itself.
tr: The text of translation key in the current language, or key itself when it has none — what Minecraft shows for an unknown key, so a missing translation is easy to spot. Call it each time the text is shown (e.g. while building a UI tree): the player can switch language at any time.
tr_args: tr with arguments for the text’s format specifiers — see format_translation. The tr! macro is shorter.
translation: The text of translation key in the current language, unformatted — None when no lang file defines it (or before the mod registered).

Attribute Macros§

bench: Inter-mod communication proc-macros. Marks a function in a mod’s benches/*.rs as a benchmark yog bench runs: fn name(b: &mut criterion::Bencher) for one benchmark, or fn name(c: &mut criterion::Criterion) to set up groups. yog generates the file’s main; this only makes the function reachable from it.
yog_export: Inter-mod communication proc-macros.
yog_mirror: Inter-mod communication proc-macros. Makes a struct a mirror’s row (see mirror.rs): #[yog_mirror(space = …, owner = "mod")], a field’s fact named by #[fact(…)].

Derive Macros§

Schema: #[derive(Schema)]: a type read and written as Yog Data (stores, packets, frames).

Crate yog_api

Crate yog_api Copy item path

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Attribute Macros§

Derive Macros§

Crate yog_api