The repository or configuration that created this release differ from a previous release. View details.
xcore-protocol
Canonical cross-service protocol for the XCore ecosystem.
Mission
xcore-protocol is the canonical source of truth for XCore cross-service communication.
It defines:
- message schemas
- envelope structure
- route and stream metadata
- versioning and compatibility rules
- canonical fixtures
- generation inputs and tooling
- generated Java and Python protocol DTO/model artifacts
- thin handwritten validation and repository-tooling support around generated artifacts
- cross-language compatibility tests
Scope
This repository contains only cross-process / cross-service wire protocol artifacts.
In scope
- event, command, and RPC contracts
- envelope definitions
- route metadata
- shared payload subtypes
- protocol fixtures and validation helpers
- generation configuration and generated Java/Python protocol artifacts
Out of scope
- application business logic
- Discord handlers or presentation code
- Mindustry runtime integration
- Mongo persistence
- app-specific reconnect/worker orchestration
Repository Layout
docs/— ADRs, architecture notes, policies, migration notesspec/— protocol specs, shared types, envelopes, routes, generation inputsfixtures/— valid, invalid, and legacy examplesgenerators/— language generation config/templates/scriptsjava/— generated Java protocol artifacts for the canonical model surfacepython/— generated Python protocol package and thin helperscompat/— cross-language compatibility checksscripts/— validation and generation helper scripts
Migrated Families
All planned message families are fully migrated and operational:
- Moderation — ban, mute, vote-kick, kick-banned, pardon, audit
- Discord — link-confirm, unlink, link-status, link-code
- Maps — list request/response, remove request/response
- Security — permission changes, staff role sync and staff password reset RPC
- Chat/Heartbeat — chat messages, global chat, heartbeat, join/leave, server actions, player state commands
- Telemetry — Redis TTL snapshot payloads for Prometheus/Gateway telemetry aggregation
Current Status
All canonical message families are defined with JSON Schema specs and canonical fixtures. Generated Java records (org.xcore.protocol.generated.*) and Python frozen dataclasses (xcore_protocol.generated.*) cover the supported generated protocol surface, including route-less telemetry snapshot payloads. XCore-plugin and XCore-discord-bot both consume generated artifacts as their sole transport model where applicable. Cross-language compatibility checks and full CI validation chain are in place.
Releases
Each vX.Y.Z tag publishes the same version of both supported artifacts:
- Java:
org.xcore:xcore-protocol-java:X.Y.Zfromhttps://maven.x-core.org/releases - Python:
xcore-protocol==X.Y.Zfrom PyPI
Production consumers must use an exact released version. Git revisions and -SNAPSHOT
versions are only acceptable while developing the protocol itself. The release workflow validates
schemas, generated output, Java tests, Python tests, and distributable packages before publishing.
Before the first PyPI release, configure the pypi GitHub environment as a PyPI Trusted Publisher
for this repository's Publish Release workflow. No Python package registry is self-hosted.
See Also
docs/adr/ADR-001-protocol-first.mddocs/architecture/protocol-overview.mddocs/policies/versioning.mddocs/policies/compatibility.md
1 maintainer
Metadata
1 maintainer
Release files for xcore-protocol 0.17.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Change of provenance
The repository or configuration that created these release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xcore_protocol-0.17.1.tar.gz | 64.9 kB | With provenance | Details for xcore_protocol-0.17.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xcore_protocol-0.17.1-py3-none-any.whl | Python 3 | none | any | Details for xcore_protocol-0.17.1-py3-none-any.whl |
Total release size: 156.1 kB
Release files / xcore_protocol-0.17.1.tar.gz
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | xcore_protocol-0.17.1.tar.gz |
|---|---|
| Size | 64.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
617695a5866697ffac901daef31cf3b5f990e1a7303cadb77bab5935e5cb4ceb
|
|
BLAKE2b-256 checksum How to use checksums |
3811941afda43c21ce1813656ca5aa7a589b3a3789e9844b39185f16b835edbb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logRelease files / xcore_protocol-0.17.1-py3-none-any.whl
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | xcore_protocol-0.17.1-py3-none-any.whl |
|---|---|
| Size | 91.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cec2a5865dc519d9b6f8a2edc910dfb032970ed73f80fecddcde8d51d69f6084
|
|
BLAKE2b-256 checksum How to use checksums |
4d7b76974210db5d3f64d973de125fc544b38d407eb073157f60a4b0818872cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logSecurity for xcore-protocol 0.17.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Change of provenance
The repository and configuration that created this release differ from a previous release.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Repository
- Removed 0.17.0 github.com/XCore-mindustry/xcore-protocol
- Added 0.17.1 github.com/XCore-mindustry/xcore
Attestation for xcore_protocol-0.17.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
