Migration Guide

Current baseline

A plugin built for API 1.0 works on every Shire 1.x Host that reports API 1.x in api.info.

Older custom builds may call game offsets directly. That code is not portable and is not part of the public API. To migrate:

List each operation the old build performed.
Map it to a public method in api-reference.md.
For reads, use player.getPosition, world.getScene, entities.list or map.getMarkers; do not read game memory.
For movement, use teleport.to; the Host validates coordinates and the teleport method.
For UI, send declarative components instead of drawing ImGui.
For settings, use the host storage instead of writing Shire's config files.
If an operation has no public adapter, it is not available yet. Request a new native operation; do not ship offset-dependent code.

The handshake reports api_version, capabilities, permissions, granted, events and ui_types.
Compare the major API version; refuse to run if it does not match.
Check capabilities before calling optional methods.
Handle -32002 not_available as a graceful degradation path.
Declare only permissions the plugin needs; new permissions require a new user approval.

Additive methods, fields and events: minor API version.
Renamed/removed methods or changed semantics: major API version + a migration note.
Host product updates and Genshin patches do not change the public method names; adapters live behind the Host.
SDKs are version-marked and should call api.info at startup when they need a feature not present in their compile-time constants.

Stored ZIP entries are required in 1.0; repack deflated packages with shire-plugin pack.
Reinstall to refresh the package hash and grant newly declared permissions.
The Host keeps approved permissions that are still declared; removed permissions are discarded.

Always rerun shire-plugin validate and the contract tests after an SDK update.