The shard-aware replacement for PlayerJoinEvent. Fired on the destination once the player’s full state has been applied, vanilla and every data adapter.
@EventHandlerpublic void onArrive(ShardPlayerArriveEvent e) { if (e.isTransfer()) return; // came from another shard if (e.isFirstJoin()) welcome(e.getPlayer());}
By the time PlayerJoinEvent fires, the inventory is not loaded yet. Anything that reads or writes player state belongs here instead.
getSource() is null for a plain login and names the shard they came from otherwise.
ShardTransferPrepareEvent
Fired on the source before any state is captured, for a border crossing and for an API transfer alike. Cancellable: cancelling keeps the player here and pushes them back inside the border.This is the last moment at which mutating the player means anything. After it, their state is snapshotted and any change is lost.
ShardTransferCommitEvent
Fired on the source once ownership has moved. The player object is still valid for a few ticks but is frozen: writes are discarded and they will disconnect shortly.Use it to clean up things that belong to this server only — scoreboards, boss bars, caches. Do not use it to give them anything.
ShardEntityCrossEvent
A non-player entity is about to be handed to a neighbour. Cancellable; cancelling keeps it here, clamped inside the border.Cancel it for entities your plugin tracks by Bukkit entity id or by reference, because on the other side it is a new entity with a new id. The mesh-wide uid on the event is stable across the crossing and is what you should key on instead.
ShardEntityArriveEvent
The other end of the same crossing. Re-attach whatever you track, keyed by the uid.
ShardRemoteKillEvent
A player on this shard killed somebody on a different one.The ordinary path cannot work across a border: a projectile resolves its shooter against the world it is in, so an arrow that crossed arrives with no attacker and everything downstream of the killer sees nothing. Atlas carries the shooter’s identity with the projectile and turns the death back into this event, fired on the killer’s shard because that is the only server that has them.
The vanilla kill statistic is already incremented before it fires. Not cancellable: by then the victim is dead on another server and there is nothing left to prevent.
ShardRemoteEditEvent
A player on a neighbouring shard is breaking, placing or hitting something on this shard’s ground, across the border. Fired on the shard that owns it, on the main thread, before anything changes — it is the owner’s half of the check, and the player’s own shard then raises an ordinary BlockBreakEvent or BlockPlaceEvent as the other half. Cancellable. Which half your setup needs is in Claims and protection.The player is not on this server, so no BlockBreakEvent, BlockPlaceEvent or EntityDamageByEntityEvent can be raised for them here. This is the event a claims or region plugin listens to instead.
@EventHandlerpublic void onRemoteEdit(ShardRemoteEditEvent e) { Block b = e.block(); // null for a hit if (b != null && !claims.canBuild(e.actor(), b.getLocation())) { e.setCancelled(true); e.setReason("That land is claimed."); }}
action() is BREAK, PLACE or HIT. actor() and actorName() identify the player across the border; placed() is the block data for a place, and target() the entity for a hit. The reason is shown to the player when the edit is refused.
ShardReadyEvent
This server has joined the mesh, announced its region, and is about to accept players. Register scheduler tasks, queries and subscriptions before or during it.
What has no event
There is no event for a block mirrored into the ghost band, and none for a ghost appearing. Both happen continuously and at a rate that would make a listener a performance problem rather than a feature. Check isGhostZone and isGhost where it matters instead.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Atlas","description":"Spatial world sharding for Paper. One Minecraft world across several servers, with borders players can walk across.","colors":{"primary":"#1E6F5C","light":"#5FBF9F","dark":"#14503F"},"logo":{"light":"https://mintcdn.com/craftsupport/MpjWOJVCDyahgiWv/logo/light.svg?fit=max\u0026auto=format\u0026n=MpjWOJVCDyahgiWv\u0026q=85\u0026s=7df739b687bf29031b961c47919e3318","dark":"https://mintcdn.com/craftsupport/MpjWOJVCDyahgiWv/logo/dark.svg?fit=max\u0026auto=format\u0026n=MpjWOJVCDyahgiWv\u0026q=85\u0026s=ab87333f9a1b792e72316ae4fa6d1b2d"},"favicon":"https://mintcdn.com/craftsupport/MpjWOJVCDyahgiWv/favicon.svg?fit=max\u0026auto=format\u0026n=MpjWOJVCDyahgiWv\u0026q=85\u0026s=b9b90d3400c0343fe76b8dd19e73b30e","navbar":{"links":[{"href":"mailto:smashyalts@gmail.com","label":"Support"}]},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"craftsupport","hasAudioNarration":false,"actualSubdomain":"craftsupport","customDomains":["docs.craftsupport.dev"],"gitSource":{"type":"github","owner":"smashyalts","repo":"mintlify-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6ad278197e75420d4b0e4bb0","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Documentation","count":22},{"language":"default","tag":"Operating","count":7},{"language":"default","tag":"Deploying","count":6},{"language":"default","tag":"Concepts","count":5},{"language":"default","tag":"API Reference","count":4},{"language":"default","tag":"Plugin API","count":4},{"language":"default","tag":"Get Started","count":2},{"language":"default","tag":"Reference","count":2}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api/events","slug":"/api/events","pageMetadata":{"title":"Events","description":"The lifecycle hooks a sharded network adds","icon":"bell","href":"/api/events"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"The lifecycle hooks a sharded network adds\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`shardplayerarriveevent`,children:`ShardPlayerArriveEvent`}),`\n`,_jsxs(_components.p,{children:[`The shard-aware replacement for `,_jsx(_components.code,{children:`PlayerJoinEvent`}),`. Fired on the destination once the player’s full state has been applied, vanilla and every data adapter.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`java`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`java`,children:_jsxs(_components.code,{language:`java`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`@`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#4EC9B0`},children:`EventHandler`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`public`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#4EC9B0`},children:` void`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` onArrive`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#4EC9B0`},children:`ShardPlayerArriveEvent`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` e) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`isTransfer`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`; `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// came from another shard`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`isFirstJoin`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()) `}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`welcome`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`getPlayer`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`());`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`By the time `,_jsx(_components.code,{children:`PlayerJoinEvent`}),` fires, the inventory is not loaded yet. Anything that reads or writes player state belongs here instead.`]})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`getSource()`}),` is null for a plain login and names the shard they came from otherwise.`]}),`\n`,_jsx(Heading,{level:`2`,id:`shardtransferprepareevent`,children:`ShardTransferPrepareEvent`}),`\n`,_jsx(_components.p,{children:`Fired on the source before any state is captured, for a border crossing and for an API transfer alike. Cancellable: cancelling keeps the player here and pushes them back inside the border.`}),`\n`,_jsx(_components.p,{children:`This is the last moment at which mutating the player means anything. After it, their state is snapshotted and any change is lost.`}),`\n`,_jsx(Heading,{level:`2`,id:`shardtransfercommitevent`,children:`ShardTransferCommitEvent`}),`\n`,_jsx(_components.p,{children:`Fired on the source once ownership has moved. The player object is still valid for a few ticks but is frozen: writes are discarded and they will disconnect shortly.`}),`\n`,_jsx(_components.p,{children:`Use it to clean up things that belong to this server only — scoreboards, boss bars, caches. Do not use it to give them anything.`}),`\n`,_jsx(Heading,{level:`2`,id:`shardentitycrossevent`,children:`ShardEntityCrossEvent`}),`\n`,_jsx(_components.p,{children:`A non-player entity is about to be handed to a neighbour. Cancellable; cancelling keeps it here, clamped inside the border.`}),`\n`,_jsx(_components.p,{children:`Cancel it for entities your plugin tracks by Bukkit entity id or by reference, because on the other side it is a new entity with a new id. The mesh-wide uid on the event is stable across the crossing and is what you should key on instead.`}),`\n`,_jsx(Heading,{level:`2`,id:`shardentityarriveevent`,children:`ShardEntityArriveEvent`}),`\n`,_jsx(_components.p,{children:`The other end of the same crossing. Re-attach whatever you track, keyed by the uid.`}),`\n`,_jsx(Heading,{level:`2`,id:`shardremotekillevent`,children:`ShardRemoteKillEvent`}),`\n`,_jsx(_components.p,{children:`A player on this shard killed somebody on a different one.`}),`\n`,_jsx(_components.p,{children:`The ordinary path cannot work across a border: a projectile resolves its shooter against the world it is in, so an arrow that crossed arrives with no attacker and everything downstream of the killer sees nothing. Atlas carries the shooter’s identity with the projectile and turns the death back into this event, fired on the killer’s shard because that is the only server that has them.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`java`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`java`,children:_jsxs(_components.code,{language:`java`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`@`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#4EC9B0`},children:`EventHandler`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`public`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#4EC9B0`},children:` void`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` onRemoteKill`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#4EC9B0`},children:`ShardRemoteKillEvent`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` e) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` economy`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`reward`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`killer`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(), `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`10`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`The vanilla kill statistic is already incremented before it fires. Not cancellable: by then the victim is dead on another server and there is nothing left to prevent.`}),`\n`,_jsx(Heading,{level:`2`,id:`shardremoteeditevent`,children:`ShardRemoteEditEvent`}),`\n`,_jsxs(_components.p,{children:[`A player on a neighbouring shard is breaking, placing or hitting something on this shard’s ground, across the border. Fired on the shard that owns it, on the main thread, before anything changes — it is the owner’s half of the check, and the player’s own shard then raises an ordinary `,_jsx(_components.code,{children:`BlockBreakEvent`}),` or `,_jsx(_components.code,{children:`BlockPlaceEvent`}),` as the other half. Cancellable. Which half your setup needs is in `,_jsx(_components.a,{href:`/deploy/protection`,children:`Claims and protection`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`The player is not on this server, so no `,_jsx(_components.code,{children:`BlockBreakEvent`}),`, `,_jsx(_components.code,{children:`BlockPlaceEvent`}),` or `,_jsx(_components.code,{children:`EntityDamageByEntityEvent`}),` can be raised for them here. This is the event a claims or region plugin listens to instead.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`java`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`java`,children:_jsxs(_components.code,{language:`java`,numberOfLines:`8`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`@`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#4EC9B0`},children:`EventHandler`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`public`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#4EC9B0`},children:` void`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` onRemoteEdit`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#4EC9B0`},children:`ShardRemoteEditEvent`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` e) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#4EC9B0`},children:` Block`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` b`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`block`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(); `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// null for a hit`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (b `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`!=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` null`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` \u0026\u0026`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` !`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`claims`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`canBuild`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`actor`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(), `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`b`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`getLocation`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`())) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`setCancelled`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`setReason`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"That land is claimed.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`action()`}),` is `,_jsx(_components.code,{children:`BREAK`}),`, `,_jsx(_components.code,{children:`PLACE`}),` or `,_jsx(_components.code,{children:`HIT`}),`. `,_jsx(_components.code,{children:`actor()`}),` and `,_jsx(_components.code,{children:`actorName()`}),` identify the player across the border; `,_jsx(_components.code,{children:`placed()`}),` is the block data for a place, and `,_jsx(_components.code,{children:`target()`}),` the entity for a hit. The reason is shown to the player when the edit is refused.`]}),`\n`,_jsx(Heading,{level:`2`,id:`shardreadyevent`,children:`ShardReadyEvent`}),`\n`,_jsx(_components.p,{children:`This server has joined the mesh, announced its region, and is about to accept players. Register scheduler tasks, queries and subscriptions before or during it.`}),`\n`,_jsx(Heading,{level:`2`,id:`what-has-no-event`,children:`What has no event`}),`\n`,_jsxs(_components.p,{children:[`There is no event for a block mirrored into the ghost band, and none for a ghost appearing. Both happen continuously and at a rate that would make a listener a performance problem rather than a feature. Check `,_jsx(_components.code,{children:`isGhostZone`}),` and `,_jsx(_components.code,{children:`isGhost`}),` where it matters instead.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Events","description":"The lifecycle hooks a sharded network adds","icon":"bell","href":"/api/events"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"ShardPlayerArriveEvent","slug":"shardplayerarriveevent","depth":2,"children":[]},{"title":"ShardTransferPrepareEvent","slug":"shardtransferprepareevent","depth":2,"children":[]},{"title":"ShardTransferCommitEvent","slug":"shardtransfercommitevent","depth":2,"children":[]},{"title":"ShardEntityCrossEvent","slug":"shardentitycrossevent","depth":2,"children":[]},{"title":"ShardEntityArriveEvent","slug":"shardentityarriveevent","depth":2,"children":[]},{"title":"ShardRemoteKillEvent","slug":"shardremotekillevent","depth":2,"children":[]},{"title":"ShardRemoteEditEvent","slug":"shardremoteeditevent","depth":2,"children":[]},{"title":"ShardReadyEvent","slug":"shardreadyevent","depth":2,"children":[]},{"title":"What has no event","slug":"what-has-no-event","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"craftsupport","siteName":"Atlas","title":"Events - Atlas","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-07T13:57:42.162Z","originalFileLocation":"api/events.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"The lifecycle hooks a sharded network adds\">\u003cmeta data-mint-head name=\"application-name\" content=\"Atlas\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Events - Atlas\">\u003cmeta data-mint-head property=\"og:description\" content=\"The lifecycle hooks a sharded network adds\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Atlas\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.craftsupport.dev/api/events\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://craftsupport.mintlify.site/_mintlify/api/og/v2?division=Plugin+API\u0026amp;title=Events\u0026amp;description=The+lifecycle+hooks+a+sharded+network+adds\u0026amp;theme=7f69d1a714fa4ad43a252e7d\u0026amp;signature=b16184770b6e5dd1366dca3c268c0580b183b62cddadc511db62922e06008ea0\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Events - Atlas\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The lifecycle hooks a sharded network adds\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://craftsupport.mintlify.site/_mintlify/api/og/v2?division=Plugin+API\u0026amp;title=Events\u0026amp;description=The+lifecycle+hooks+a+sharded+network+adds\u0026amp;theme=7f69d1a714fa4ad43a252e7d\u0026amp;signature=b16184770b6e5dd1366dca3c268c0580b183b62cddadc511db62922e06008ea0\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/craftsupport/eF8MciFWfwuJS6Vh/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Atlas\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#1E6F5C\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.craftsupport.dev/api/events\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/events.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.craftsupport.dev/#organization\",\"name\":\"Atlas\",\"url\":\"https://docs.craftsupport.dev\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/craftsupport/MpjWOJVCDyahgiWv/logo/light.svg?fit=max\u0026auto=format\u0026n=MpjWOJVCDyahgiWv\u0026q=85\u0026s=7df739b687bf29031b961c47919e3318\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.craftsupport.dev#website\",\"name\":\"Atlas\",\"url\":\"https://docs.craftsupport.dev\",\"publisher\":{\"@id\":\"https://docs.craftsupport.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.craftsupport.dev/api/events#webpage\",\"url\":\"https://docs.craftsupport.dev/api/events\",\"name\":\"Events\",\"description\":\"The lifecycle hooks a sharded network adds\",\"dateModified\":\"2026-10-07T13:57:42.162Z\",\"isPartOf\":{\"@id\":\"https://docs.craftsupport.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.craftsupport.dev/api/events#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.craftsupport.dev/api/events#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Plugin API\",\"item\":\"https://docs.craftsupport.dev/api/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Events\",\"item\":\"https://docs.craftsupport.dev/api/events\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.craftsupport.dev/api/events#article\",\"headline\":\"Events\",\"name\":\"Events\",\"description\":\"The lifecycle hooks a sharded network adds\",\"url\":\"https://docs.craftsupport.dev/api/events\",\"mainEntityOfPage\":{\"@id\":\"https://docs.craftsupport.dev/api/events#webpage\"},\"dateModified\":\"2026-10-07T13:57:42.162Z\",\"publisher\":{\"@id\":\"https://docs.craftsupport.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.craftsupport.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Atlas\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Atlas\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api/events.md","siteName":"Atlas","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"Plugin API","icon":"plug","pages":[{"title":"Overview","icon":"plug","href":"/api/overview"},{"title":"Player data","description":"Making your state travel with the player","icon":"suitcase","href":"/api/player-data"},{"title":"Events","icon":"bell","href":"/api/events"},{"title":"Worked example","description":"The three teleport features every server has, written for a sharded one","icon":"code","href":"/api/example"}]}]}]},"basePath":"","title":"Events - Atlas","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}