API stability

Public types carry a stability level through the @ApiStability annotation in the code. If this page and the code disagree, the code is correct.

No API is STABLE yet

The first public API stays PREVIEW until it has been used in practice. All Native APIs that mods use are PREVIEW and can change between versions.

Levels

Level	Meaning
STABLE	API with a compatibility promise (none yet)
PREVIEW	Public API that can change
VERSION_BOUND	Implementation tied to a specific Minecraft version
INTERNAL	For Poly Mod Loader internals. Mods must not use it
UNSAFE	Risky feature that changes the game directly

Behavior categories

These show what each type can do: READ, WRITE, REGISTER, EXTEND, REPLACE, INTERCEPT, TRANSFORM, MIGRATE, INSPECT, and OBSERVE for events.

Summary by area

All types are under dev.polymodloader.api and have the level PREVIEW.

Area	Main types	Timing and thread
Lifecycle	CommonModInitializer, ClientModInitializer, DedicatedServerModInitializer, ModContext	Dependency order, main thread, before the game main
Events	EventKey, EventRegistry, ServerEvents, ServerView	Register at any time (thread-safe). Server events run on the server thread
Systems	SystemId, SystemProvider, SystemLookup, GameBrandSystem	Providers: main thread, once before entrypoints
Content	ContentRegistrar, BlockDefinition, ItemDefinition, BlockBehavior, ItemBehavior, CreativeTab, ResourceId	Declaration: common entrypoint. Behavior: world thread, both sides
Block state and block entities	BlockProperty, BlockStateView, BlockEntityDefinition, BlockEntityView, MenuLayout, InventoryView	World thread. Ticks: server thread
Item data	ItemComponentKey, ComponentType, ItemStackRef	World thread
World and entities	WorldView, EntityView, LivingEntityView, MobView, PlayerView, StoredData, DataTree	World thread, valid only during the callback. Changes happen on the server
Mobs and gameplay	EntityDefinition, AiGoal, ProjectileDefinition, EffectDefinition, GameRuleKey, AdvancementTrigger	Server thread (behavior)
World generation	WorldgenRegistrar, BiomeSelector, BiomeDefinition, TerrainGenerator, ColumnBuilder	Common entrypoint. Terrain generator: world generation threads (concurrent calls)
Commands and permissions	CommandRegistrar, CommandNode, CommandContext, CommandSource, PermissionRegistrar, PermissionNode, PermissionProvider	Server thread. Installed at each server start and /reload
Network	NetworkRegistrar, PayloadChannel, PayloadCodec	Send: server/client thread. Codec: network thread (no game state access)
Client	ClientRegistrar, KeyBinding, HudCanvas, ClientView, ModScreen, BlockEntityCanvas, DynamicTexture, ClientEvents	Client thread. HUD, drawing, field of view: render thread, every frame
Resources	ResourceRegistrar, ResourceReloadListener, BinaryReloadListener	Reload apply thread
Storage and sync	EntityDataKey, EntityDataOptions, StorageOptions, DataMigration	Server thread. The client gets a read-only copy
Game tests	GameTestRegistrar, GameTestContext, TestArea	Server thread of the game test server

Internal APIs

Package	Level
dev.polymodloader.internal.transform.* (transform rules)	INTERNAL. Mods cannot use it yet. Mods declare transforms with transforms in poly.mod.json
dev.polymodloader.game.version.* (version adapter contract)	INTERNAL
Version adapters and game layers	VERSION_BOUND

The status of each poly.mod.json field is in the poly.mod.json schema.