{"id":19079066,"url":"https://github.com/minekube/common","last_synced_at":"2025-08-26T16:24:29.216Z","repository":{"id":57532736,"uuid":"279371574","full_name":"minekube/common","owner":"minekube","description":"Minecraft text component library \u0026 more!","archived":false,"fork":false,"pushed_at":"2024-12-11T12:59:33.000Z","size":60,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-11T13:46:20.330Z","etag":null,"topics":["color","component","convert","decode","encode","hex","json","legacy","minecraft","text"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minekube.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-13T17:41:06.000Z","updated_at":"2024-12-11T12:58:22.000Z","dependencies_parsed_at":"2023-02-08T21:35:12.057Z","dependency_job_id":"1630b22d-aa51-4202-9f83-8067e8128403","html_url":"https://github.com/minekube/common","commit_stats":{"total_commits":26,"total_committers":2,"mean_commits":13.0,"dds":"0.11538461538461542","last_synced_commit":"bf1cb5667e75292d2403972e99c59f04e61c2ac7"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minekube%2Fcommon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minekube%2Fcommon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minekube%2Fcommon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minekube%2Fcommon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minekube","download_url":"https://codeload.github.com/minekube/common/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232242736,"owners_count":18493786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["color","component","convert","decode","encode","hex","json","legacy","minecraft","text"],"created_at":"2024-11-09T02:13:12.892Z","updated_at":"2025-08-26T16:24:29.209Z","avatar_url":"https://github.com/minekube.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Minekube Commons Library\n\n**Get it:**\n`go get -u go.minekube.com/common`\n\n## Minecraft Text Components (`minecraft/component`)\n\nA comprehensive Minecraft text components library with **full multi-version support** for all Minecraft versions from legacy to the latest (1.21.6+).\n\n### 🎯 Key Features\n\n- **Complete Multi-Version Support**: Supports all Minecraft versions from legacy to 1.21.6+\n- **Backward \u0026 Forward Compatibility**: Can decode any format regardless of encoding settings\n- **Configurable Encoding**: Choose between formats for different Minecraft versions\n- **High Performance**: Uses optimized JSON marshalling (thanks to [Gojay](https://github.com/francoispqt/gojay))\n- **Complete Component Support**: Text, translation, click events, hover events, styling, and more\n- **Future-Ready**: Includes upcoming 1.21.6+ features like dialog and custom click events\n\n### 🚀 Quick Start\n\n```go\nimport \"go.minekube.com/common/minecraft/component/codec\"\n\n// Create a codec for the latest format (1.21.5+)\nj := \u0026codec.Json{\n    UseLegacyFieldNames:          false, // Use snake_case field names\n    UseLegacyClickEventStructure: false, // Use specific field names\n    UseLegacyHoverEventStructure: false, // Use inlined structure\n    StdJson:                      true,\n}\n\n// Create a text component with click and hover events\ncomponent := \u0026component.Text{\n    Content: \"Click me!\",\n    S: component.Style{\n        Color:      color.Green.RGB,\n        ClickEvent: component.OpenUrl(\"https://example.com\"),\n        HoverEvent: component.ShowText(\u0026component.Text{Content: \"Tooltip\"}),\n    },\n}\n\n// Encode to JSON\nvar buf strings.Builder\nerr := j.Marshal(\u0026buf, component)\n// Output: {\"text\":\"Click me!\",\"color\":\"#55ff55\",\"click_event\":{\"action\":\"open_url\",\"url\":\"https://example.com\"},\"hover_event\":{\"action\":\"show_text\",\"value\":{\"text\":\"Tooltip\"}}}\n```\n\n### 📋 Supported Click Events\n\n| Action              | Legacy Field | Modern Field(s) | Version | Description                       |\n| ------------------- | ------------ | --------------- | ------- | --------------------------------- |\n| `open_url`          | `value`      | `url`           | 1.21.5+ | Opens URL in browser              |\n| `open_file`         | `value`      | `path`          | 1.21.5+ | Opens file (client-side only)     |\n| `run_command`       | `value`      | `command`       | 1.21.5+ | Executes command                  |\n| `suggest_command`   | `value`      | `command`       | 1.21.5+ | Suggests command in chat          |\n| `change_page`       | `value`      | `page`          | 1.21.5+ | Changes book page (int in modern) |\n| `copy_to_clipboard` | `value`      | `value`         | All     | Copies text (unchanged)           |\n| `show_dialog`       | `value`      | `dialog`        | 1.21.6+ | Opens dialog                      |\n| `custom`            | `value`      | `id`/`payload`  | 1.21.6+ | Custom server event               |\n\n### 🎛️ Version Configuration Examples\n\n**Using Preset Configurations (Recommended):**\n\n```go\nimport \"go.minekube.com/common/minecraft/component/codec\"\n\n// For clients before 1.16\nj := codec.JsonPre1_16\n\n// For clients 1.16+ but before 1.20.3\nj := codec.JsonPre1_20_3\n\n// For clients 1.20.3+ but before 1.21.5\nj := codec.JsonPre1_21_5\n\n// For clients 1.21.5+ (latest format)\nj := codec.JsonModern\n\n// Universal compatibility (encodes modern, decodes all)\nj := codec.JsonUniversal\n```\n\n**Manual Configuration:**\n\n```go\n// Latest Format (1.21.6+)\nj := \u0026codec.Json{\n    UseLegacyFieldNames:          false, // snake_case: click_event, hover_event\n    UseLegacyClickEventStructure: false, // Specific fields: url, path, command, etc.\n    UseLegacyHoverEventStructure: false, // Inlined hover structure\n    StdJson:                      true,\n}\n\n// Legacy Format (Pre-1.21.5)\nj := \u0026codec.Json{\n    UseLegacyFieldNames:          true,  // camelCase: clickEvent, hoverEvent\n    UseLegacyClickEventStructure: true,  // Universal \"value\" field\n    UseLegacyHoverEventStructure: true,  // \"contents\" wrapper structure\n    NoLegacyHover:                false, // Include both contents and value\n    StdJson:                      true,\n}\n```\n\n**Preset Configurations:**\n\n| Preset          | Target Version  | Field Names | Click Events      | Hover Events      | Features                    |\n| --------------- | --------------- | ----------- | ----------------- | ----------------- | --------------------------- |\n| `JsonPre1_16`   | Before 1.16     | camelCase   | Universal \"value\" | Legacy + value    | Color downsampling          |\n| `JsonPre1_20_3` | 1.16 - 1.20.2   | camelCase   | Universal \"value\" | Legacy + contents | Hex colors                  |\n| `JsonPre1_21_5` | 1.20.3 - 1.21.4 | camelCase   | Universal \"value\" | Legacy + contents | Compact text, int UUIDs     |\n| `JsonModern`    | 1.21.5+         | snake_case  | Specific fields   | Inlined           | All modern features         |\n| `JsonUniversal` | Any             | snake_case  | Specific fields   | Inlined           | Decodes all, encodes modern |\n\n### ⚙️ Advanced JSON Configuration Options\n\nFor fine-grained control over JSON serialization behavior, additional options are available that correspond to Minecraft's internal JSON serialization flags:\n\n```go\nj := \u0026codec.Json{\n    // Basic structure control\n    UseLegacyFieldNames:          false, // snake_case vs camelCase field names\n    UseLegacyClickEventStructure: false, // Specific fields vs universal \"value\"\n    UseLegacyHoverEventStructure: false, // Inlined vs \"contents\" wrapper\n\n    // Version-specific behavior control\n    EmitChangePageClickEventPageAsString:     false, // Page as int (1.21.6+) vs string (legacy)\n    EmitCompactTextComponent:                 true,  // Plain text optimization (1.20.3+)\n    EmitHoverShowEntityIdAsIntArray:          true,  // UUID as int array (1.20.3+) vs string\n    EmitHoverShowEntityKeyAsTypeAndUuidAsId:  false, // Modern (\"id\"/\"uuid\") vs legacy (\"type\"/\"id\") field names\n    ValidateStrictEvents:                     true,  // Strict event validation (1.20.3+)\n    EmitDefaultItemHoverQuantity:             true,  // Always emit count=1 (1.20.5+)\n\n    // Advanced formatting modes\n    ShowItemHoverDataMode: codec.ShowItemHoverDataModeDataComponents, // Legacy NBT vs modern data components\n    ShadowColorMode:       codec.ShadowColorEmitModeInteger,          // Shadow color format (1.21.4+)\n\n    StdJson: true,\n}\n```\n\n**Configuration Options:**\n\n| Option                                    | Description                               | Default     | Since Version |\n| ----------------------------------------- | ----------------------------------------- | ----------- | ------------- |\n| `EmitChangePageClickEventPageAsString`    | Emit page numbers as strings vs integers  | `false`     | 1.21.6+       |\n| `EmitCompactTextComponent`                | Use plain text for simple components      | `false`     | 1.20.3+       |\n| `EmitHoverShowEntityIdAsIntArray`         | UUID as `[int, int, int, int]` vs string  | `false`     | 1.20.3+       |\n| `EmitHoverShowEntityKeyAsTypeAndUuidAsId` | Use legacy field names (`\"type\"`, `\"id\"`) | `true`      | Pre-1.21.5    |\n| `ValidateStrictEvents`                    | Enable strict event validation            | `false`     | 1.20.3+       |\n| `EmitDefaultItemHoverQuantity`            | Always emit `count: 1` for items          | `false`     | 1.20.5+       |\n| `ShowItemHoverDataMode`                   | Item data format (NBT vs data components) | `LegacyNBT` | 1.20.5+       |\n| `ShadowColorMode`                         | Shadow color emission format              | `None`      | 1.21.4+       |\n\n**ShowItemHoverDataMode Values:**\n\n- `ShowItemHoverDataModeLegacyNBT` - Use legacy NBT format\n- `ShowItemHoverDataModeDataComponents` - Use modern data components\n- `ShowItemHoverDataModeEither` - Use whichever the item has\n\n**ShadowColorMode Values:**\n\n- `ShadowColorEmitModeNone` - Don't emit shadow colors\n- `ShadowColorEmitModeInteger` - Emit as packed ARGB integer\n- `ShadowColorEmitModeArray` - Emit as `[r, g, b, a]` float array\n\n### 🆕 New Minecraft 1.21.6 Features\n\n```go\n// Dialog click event (1.21.6+)\ndialogComponent := \u0026component.Text{\n    Content: \"Open Settings\",\n    S: component.Style{\n        ClickEvent: component.ShowDialog(\"settings_dialog\"),\n    },\n}\n\n// Custom server events (1.21.6+)\ncustomComponent := \u0026component.Text{\n    Content: \"Trigger Event\",\n    S: component.Style{\n        ClickEvent: component.CustomEvent(\"my_event\", \"some_payload\"),\n    },\n}\n```\n\n### 🔄 Format Examples\n\n**Modern Format (1.21.5+):**\n\n```json\n{\n  \"text\": \"Click me\",\n  \"click_event\": {\n    \"action\": \"open_url\",\n    \"url\": \"https://example.com\"\n  },\n  \"hover_event\": {\n    \"action\": \"show_item\",\n    \"id\": \"minecraft:diamond\",\n    \"count\": 5\n  }\n}\n```\n\n**Legacy Format (Pre-1.21.5):**\n\n```json\n{\n  \"text\": \"Click me\",\n  \"clickEvent\": {\n    \"action\": \"open_url\",\n    \"value\": \"https://example.com\"\n  },\n  \"hoverEvent\": {\n    \"action\": \"show_item\",\n    \"contents\": {\n      \"id\": \"minecraft:diamond\",\n      \"count\": 5\n    }\n  }\n}\n```\n\n### ✨ Additional Features\n\n- **Legacy colors \u0026 formats**: Support for legacy color codes\n- **Minecraft 1.16+ hex colors**: Full hex color support (`#ff5555`)\n- **Hover events**: `show_text`, `show_item`, `show_entity` with all format variations\n- **Translations**: Full translation component support with arguments\n- **Cross-version compatibility**: Decode any format, encode in your preferred format\n- **Performance optimized**: Much faster than Go's standard JSON encoding\n- **Comprehensive testing**: Extensive test coverage for all versions and formats\n\n### 🧪 Testing, formatting, linting\n\n```bash\nmake\n```\n\nAll format variations and cross-compatibility scenarios are thoroughly tested to ensure reliability across all Minecraft versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminekube%2Fcommon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminekube%2Fcommon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminekube%2Fcommon/lists"}