Files
+16 078446694c Add Crowdin, introduce new provider schema, introduce NetherNet blog post (#51)
* Begin testing i18n

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Add crowdin in-context demo for non-mdx

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Add crowdin-sync system

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Working sync system for translations

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Only build en locale for PRs

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Modify yarn install

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Do not immute cache

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Try with standard yarn install

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Revert to yarn --immutable

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Remove explicit url/file-loader resolutions

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Only log webpack errors

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Added MCServerHost to hosting providers (#47)

* Added MCServerHost to hosting providers

* Update providers.ts

* Correct grammar and make instructions more concise

---------

Co-authored-by: Kas-tle <26531652+Kas-tle@users.noreply.github.com>

* Update supported Bedrock versions

* Remove and Replace "TydiumCraft Skin API" (#53)

* Update community-geyser-projects.md

I no longer will run TydiumCraft Skin API. I have no interest in continuing it at this time (or anything minecraft related). However I have switched out the spot with an API that 100% is always updated and active. Hosted by my good friend Bret06. This works so much better as well. Thanks for everything over the years guys! Tydium out!

* Update wiki/other/community-geyser-projects.md

👍

Co-authored-by: chris <github@onechris.mozmail.com>

---------

Co-authored-by: chris <github@onechris.mozmail.com>

* Update wording for creepernation api

Update wording because it’s bothering me

* Update GeyserExtras description  (#52)

* Update community-geyser-projects.md

* Update wiki/other/community-geyser-projects.md

Co-authored-by: chris <github@onechris.mozmail.com>

---------

Co-authored-by: Luke <32024335+lukeeey@users.noreply.github.com>
Co-authored-by: chris <github@onechris.mozmail.com>

* Try matrix build strategy

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Fix matrix output

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Matrix goes to GITHUB_OUTPUT

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Fix deploy needs to combine

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Ensure correct commit is used if crowdin updates

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Make sure excluded content is respected

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Allow permission for commit action write

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Sync translations with Crowdin

* Update index.md to make clear that this is for servers, not purely for clients (#57)

* Update providers.ts (#58)

* Update providers.ts

VemoxHost added

* Maintain alphabetized list

---------

Co-authored-by: Kas-tle <26531652+Kas-tle@users.noreply.github.com>

* Start on re-writing the providers page to provide more useful details to improve the setup guide

* more work on this

* Rework paper page for setup

* Don't try and build paper setup as a full page

* adjust not listed message

* update mod/proxy pages

* Initial setup i18n

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Add ability to hide proxy setup instructions by provider

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Temporary auto deployment; fix broken links

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Fix heading consistency

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Update language on provider instructions

* Update language on new provider instructions

* Upgrade actions/setup-node due to hang issue

* Both

* Forgot how many times we setup node...

* Documentation for changes in API/2.6.2 (#62)

* Document latest Geyser changes:
- remote resource packs

* Update/Finish pack docs

* small typo fixes

* Update page content

* fix build

* Update supported Bedrock version

* Add Modrinth Servers to providers (#63)

* Update supported versions & api version

* Update versions.json to include 1.21.72 (#64)

* Update bedrock version (#67)

* Add 'we are not mojang' disclaimer to footer

* Stop translations from overriding footer message

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Fix Standalone dump view (#68)

* Add OrionNodes to providers (#69)

* Update supported Bedrock versions in versions.json (1.21.81, 1.21.82) (#70)

* Update faq.mdx to include recommended API (#73)

Tydium skin API is abandoned, please direct users to a working API such as the one recommended by Tydium

Derived from: https://github.com/GeyserMC/GeyserWebsite/commit/19ae50f95ddbfc24ff34a42d278bdc263e0200e6

* Update anticheat-compatibility.md (#74)

* Update versions.json

* Update versions.json (#75)

* Remove LAC because it is no longer being maintained (#76)

* Update versions.json for 1.21.7 (#77)

* Update versions.json for 1.21.93 (#78)

* Update versions.json for 1.21.94 (#79)

* Update versions.json for Java 1.21.8 (#80)

* Update Geyser Api version (#81)

* Readd Hydraulic and add Rainbow, provide Item API V2 warning for Hydraulic (#82)

* Fix incorrect Ubuntu on Oracle Cloud instructions (#84)

* Remove Geyser Android App and Tempest (#83)

* Update version.json for 1.21.100 (#88)

* Update getting-started-with-the-api.md (#89)

* Add and update wiki pages, add Thunder download. (#90)

* Add a Thunder and Rainbow wiki page, touch up some other pages

* Fix mobile sidebar

* Address review 1/2

* Address review 1.5/2 (oops)

* Address review 2/2

Co-authored-by: chris <github@onechris.mozmail.com>

---------

Co-authored-by: chris <github@onechris.mozmail.com>

* Indicate 1.21.101 on the Geyser Website (#93)

* Added GeyserFloatingPoints to FAQ (#92)

* Added GeyserFloatingPoints.

* Update wiki/geyser/faq.mdx

Co-authored-by: chris <github@onechris.mozmail.com>

---------

Co-authored-by: chris <github@onechris.mozmail.com>

* Update versions.json to indicate support for bedrock 1.21.111

* Update versions.json for Java 1.21.9/1.21.10 (#97)

* Update versions.json for Java 1.21.9

* Update versions.json to include 1.21.10

* Update supported Bedrock version

---------

Co-authored-by: Aurorawr <auroranova8756@gmail.com>
Co-authored-by: chris <github@onechris.mozmail.com>

* Update extensions file for new dependency system (#98)

* Update extensions file for new dependency system

* Update version

* Update wiki/geyser/extensions.md

---------

Co-authored-by: chris <github@onechris.mozmail.com>

* Replace the Crowdin link with the current one (#101)

* Replace the Crowdin link with the current one

* Replace the link with the subdomain redirect

* Update versions.json to include 1.21.114 (#102)

* Update rainbow.md to indicate 1.21.9/.10 (#103)

* Revise port forwarding instructions for Ubuntu

Updated instructions for allowing Minecraft and Geyser through the OS firewall on Ubuntu.

* Update providers and deploy action

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Sync translations with Crowdin

* Correct providers syntax

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Use more templates wherever possible

* Add build cache; update docusaurus-og

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Test deploy time with cache hit

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Use read-only cache for matrix build

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Unlikely we will use gh actions on arm...

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* This time cache will hit

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Hopefully correct yarn cache path...

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Maybe npm?

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Surely...

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* This time...

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Include yarn/docusaurus cache for PRs

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Add page IDs to more pages, fix broken pages

* Update i18n pages

* Sync translations with Crowdin

* Add missing support pages and articles on providers, add Discord links

* Add blog post on preparing Geyser servers for NetherNet

Drafted with the help of Claude Opus 5.5.

* Rewrite the hosted setup guide for NetherNet, add hosting page

Provider entries now describe ports, signaling and install steps, grouped
in the order the setup guide shows them. The guide generates the NetherNet
config from them, and the old supported hosting providers list is replaced
by a hosting page for Open Collaboration supporters.

Drafted with the help of Claude Opus 5.5.

* Rewrite the self-hosted setup guides for NetherNet

The self-hosting pages now use the same steps and generated config as the
hosted guide, and point out that the Geyser port needs both TCP and UDP.

Drafted with the help of Claude Opus 5.5.

* Add HTTPS for NetherNet page

Covers serving built-in signaling over HTTPS, with a certificate in the
Geyser config or with a reverse proxy (Caddy, nginx).

Drafted with the help of Claude Opus 5.5.

* Skip Crowdin sync in deploy workflow when no token is set

Forks do not have the Crowdin secrets, so the sync step failed there and
nothing got deployed. Without a token, the workflow now builds and deploys
the pushed commit as is.

Drafted with the help of Claude Opus 5.5.

* Address: rtm's comments

* Improve layout, drop confusing 26.40 note on setup guide

* Cleanup blog post language / line breaks

* Merge proxy server guides for server hosts, adjust exarotron provider entry, adjust setup guides to work with crowdin

* Split the proxy setup guides back into Velocity and BungeeCord

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Update hosting providers to upstream and collapse strings into defaults

Port upstream's provider changes to the new format: add Minehost and
ConsulHosting, update MCServerHost, rename Feather to Dawn and Modrinth
Servers to Modrinth Hosting, merge RamShard into RackGenius, add MyArena,
and drop hosts upstream removed. Restore link fixes the rewrite undid
and install details dropped from the live page.

Replace host-specific strings with templates or the generated steps
where they say the same thing. Hosts that pick the port themselves show
where it comes from instead of the config step.

Hosts without NetherNet details that shared the Java server's port now
ask for a new port, open for both TCP and UDP, and the generated config
turns clone-remote-port off. Hosts that cannot give out a port fall back
to the "Not listed" guide for the Java server's port, which uses Warden.
BisectHosting no longer uses assumed example data. Entries keep the date
of their last edit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Remove Dawn and date Aternos and exaroton today

Dawn now integrates with Aternos, so it no longer needs its own entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Remove unused translation strings and fix the English GeyserConnect text

Drop keys the code no longer uses from every locale: the old EmoteOffhand
description ID, the theme's old unlisted content strings, strings removed
on this branch, and the removed Custom Resource Packs sidebar category.
The English GeyserConnect description had an outdated message that
overrode the current one on the English site.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Hide the NetherNet and RakNet option when only the Java port is available

With only the Java server's port there is no second UDP port for RakNet,
so the "Not listed" Java port guide shows the NetherNet config without
transport tabs. Drop the placeholder text that only applied there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add an HTTPS step to the self-hosted guides and correct external signaling HTTPS claims

Self-hosted guides end with a recommended step to serve signaling over
HTTPS, since Geyser's built-in signaling uses plain HTTP by default and
players get a "Trust on First Use?" prompt. External signaling services
do not all provide HTTPS, so the blog post and HTTPS page now name Warden
as one that does instead of implying all do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Update port forwarding guide, update OVH note

* Sync translations with Crowdin

* Hide entire placeholder strings and correcntly mark chrome json in crowdin

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Update actions and yarn

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Sync translations with Crowdin

* Apply batched suggestions from code review

Co-authored-by: Eclipse <eclipse@eclipseisoffline.xyz>

* Fix NetherNet docs for the final Geyser PR

- Built-in signaling serves HTTPS instead of HTTP once a certificate is configured (blog, system properties)
- "Free port" is now "available port" in the blog
- System properties: drop the removed "none" signaling mode, fix the signaling port default
- playit.gg: note that the guide is for RakNet, and link playit.gg's NetherNet progress

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Build the setup guides from translation strings

The per-platform setup pages are replaced by SetupGuide.tsx, which renders the
hosted and self-hosted guides from shared MDXTranslatable strings, so Crowdin
translates each sentence once instead of every page separately.

Also:
- "Not listed" with only the Java port sets mode: nxs instead of relying on Geyser's fallback
- The playit.gg note links playit.gg's NetherNet progress instead of describing a setup
- "free port" is now "available port"

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Remove the trustedProxies.fetch system property for now

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fix crowdin sync and don't translate trade names

Signed-off-by: GitHub <noreply@github.com>

* Sync translations with Crowdin

* Fix build

Signed-off-by: GitHub <noreply@github.com>

* Sync translations with Crowdin

* Address more concerns with nethernet https guide

Signed-off-by: GitHub <noreply@github.com>

* Fix signaling-trusted-proxies config in nethernet https article

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>

* Remove port forwarding from the HTTPS guide

Ports are already covered by the setup guide, and HTTPS does not change
which ports need to be opened. Reverse proxies now use
signaling-trusted-proxies, which reads X-Forwarded-For.

* Remove placeholder hosts, hide the hosting page until it launches

- Remove the placeholder hosts and their logos
- Aternos and exaroton are bronze supporters: highlighted with a badge in
  the setup guide, without a "last updated" date, but not listed on the
  hosting page, which only shows gold and silver
- Hide the hosting page and its links for now, and mention in the blog
  post that it is coming soon

* Supporting hosts configure Geyser, they do not install it

* Sync translations with Crowdin

* Move nethernet https guide up on sidebar

* Update to docusaurus 3.10 and fix all type errors

Signed-off-by: GitHub <noreply@github.com>

* HTTP and HTTPS do not both run at once

* Link win-acme's and nginx's own Windows guides in the HTTPS guide

* Fix crowdin key exclusion logic

Signed-off-by: GitHub <noreply@github.com>

* Sync translations with Crowdin

* Address reviews, clear up instructions for users. Adds info on haproxy, NXS and MOTD forwarding

* Note certificate permissions and where to save the Caddyfile

* Sync translations with Crowdin

* Document the geyser nethernet command

* Sync translations with Crowdin

* Support directly linking to the "not listed" or a specific hosts' guide

* Mention warden supporting custom domains

* Add HOSTING_PROVIDERS.md, update existing server host setup entries to reduce translation strings used

* Sync translations with Crowdin

---------

Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com>
Signed-off-by: GitHub <noreply@github.com>
Co-authored-by: Yara Durand <87721861+Roolps@users.noreply.github.com>
Co-authored-by: chris <github@onechris.mozmail.com>
Co-authored-by: Tydium <67938521+Tydium@users.noreply.github.com>
Co-authored-by: Creeperz653 <76449952+Creeperz653@users.noreply.github.com>
Co-authored-by: LetsGoAway <68365423+letsgoawaydev@users.noreply.github.com>
Co-authored-by: Luke <32024335+lukeeey@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Dan <20766261+D4n2021@users.noreply.github.com>
Co-authored-by: santevemox <57247088+santevemox@users.noreply.github.com>
Co-authored-by: rtm516 <ryantmilner@hotmail.co.uk>
Co-authored-by: Emma Alexia <wafflecoffee7@gmail.com>
Co-authored-by: Alex <zomka@fard.ing>
Co-authored-by: Aurorawr <100384210+Novampr@users.noreply.github.com>
Co-authored-by: Jens Collaert <63231928+Jens-Co@users.noreply.github.com>
Co-authored-by: OrionNodes <ethan@orionnodes.com>
Co-authored-by: SylentHuntress <91935048+sylenthuntress@users.noreply.github.com>
Co-authored-by: oryxel <gamingnoob681@gmail.com>
Co-authored-by: Eclipse <eclipse@eclipseisoffline.xyz>
Co-authored-by: Nebojsa Majic <79749977+Onako2@users.noreply.github.com>
Co-authored-by: qscbm187531 <1309635304@qq.com>
Co-authored-by: Eveline Carter <6444703+drakon64@users.noreply.github.com>
Co-authored-by: SleepyPop <81194303+SleepyPopp@users.noreply.github.com>
Co-authored-by: Aurorawr <auroranova8756@gmail.com>
Co-authored-by: rtm516 <rtm516@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 19:42:47 -07:00

25 KiB

title, description, crowdin_page_id
title description crowdin_page_id
Custom Blocks Geysers allows custom blocks to be mapped to Vanilla Java blockstates or modded blocks to allow custom block models. 44954bd0-b952-447f-bf94-088e679a2d0f

To setup custom blocks in geyser, you have to choose how you are going to register your blocks. The easiest is using a json file but you can also use a Geyser extension.

It should be noted that blocks and their associated components are not very stable. Mojang tends to make changes to these much more often than they do for items. This means that any components Geyser allows you to register are liable to break in future versions of Bedrock.

:::warning Geyser does not convert resource packs from Java Edition, and also does not generate custom block mappings automatically. However, you can use automatic tools such as Rainbow to make converting content simpler. :::

Enabling custom blocks

Before beginning, ensure that gameplay.enable-custom-content is set to true in your config.yml file.

# Whether to add any items and blocks which normally does not exist in Bedrock Edition.
# This should only need to be disabled if using a proxy that does not use the "transfer packet" style of server switching.
# If this is disabled, furnace minecart items will be mapped to hopper minecart items.
# Geyser's block, item, and skull mappings systems will also be disabled.
# This option requires a restart of Geyser in order to change its setting.
enable-custom-content: true

JSON mappings

The JSON mappings use a similar structure to that of behavior packs registering blocks. The equivalent components are listed in the Minecraft: Bedrock Edition Creator Documentation.

Custom mappings files that register blocks or items should be placed in the custom_mappings folder. This folder is created when you start your server. It is located in the same folder as the Geyser-Standalone.jar file for standalone and inside your Geyser data folder for a plugin. If you do not have this folder, ensure you are on the latest version of Geyser.

Example mappings file

{
	"format_version": 1,
	"blocks": {
		"minecraft:granite_wall": {
			"name": "my_block",
			"display_name": "Custom Granite Wall",
			"geometry": "geometry.blocks.my_block_geo",
			"material_instances": {
				"*": {
					"texture": "some_texture",
					"render_method": "alpha_test",
					"face_dimming": true,
					"ambient_occlusion": true
				}
			},
			"tags": ["stone", "wall"],
			"state_overrides": {
				"east=none,north=none,south=none,up=true,waterlogged=true,west=none": {
					"geometry": "geometry.blocks.my_other_block_geo",
					"destructible_by_mining": 10,
					"place_air": false
				},
				"east=none,north=none,south=none,up=false,waterlogged=true,west=tall": {
					"friction": 0.6,
					"light_emission": 7,
					"light_dampening": 8,
					"transformation": {
                        "scale": [0.5, 0.5, 0.5],
                        "translation": [1, 0, 0],
                        "rotation": [0, 90, 0]
                    }
				},
				"east=none,north=none,south=low,up=true,waterlogged=true,west=tall": {
					"placement_filter": {
						"conditions": [{
							"allowed_faces": ["up", "down"],
							"block_filter": [{
									"tags": "!query.any_tag('stone')"
								},
								"minecraft:dirt"
							]
						}]
					}
				}
			}
		}
	}
}

Schema

The following details the schema for the mappings file. Only the name field is strictly required. All other fields are optional.

  • format_version:
    • Type: integer
      • Description: The version of the format of the mappings file.
  • blocks:
    • Type: object
      • Description: An object containing a list of block definitions.
        • minecraft:some_block:
          • Type: object
            • Description: A block definition to be used to override the specified java block.
              • name:
                • Type: string
                  • Default: none
                  • Description: The name of the custom block.
              • collision_box:
                • Type: object or array of objects for multiple collision boxes
                  • origin:
                    • Type: array
                      • Default: Inferred from overridden block
                      • Description: An array of x, y, and z origin values
                      • Range: Must be in range [-8, 0, -8] to [8, 24, 8], inclusive
                        • items:
                          • Type: float
                            • Default: Inferred from overridden block
                            • Description: An origin value for a single axis
                  • size:
                    • Type: array
                      • Default: Inferred from overridden block
                      • Description: An array of x, y, and z size values
                      • Range: Must be in range [0, 0, 0] to [16, 24, 16], inclusive
                        • items:
                          • Type: float
                            • Default: Inferred from overridden block
                            • Description: An size value for a single axis
                  • Range: The sum of origin and size must be in range [-8, 0, -8] to [8, 24, 8], inclusive.
              • destructible_by_mining:
                • Type: integer
                  • Default: Inferred from overridden block
                  • Description: The time in seconds to mine the block with base tools.
              • display_name:
                • Type: string
                  • Default: the name of the custom block
                  • Description: The display name of the block.
              • friction:
                • Type: float
                  • Range: 0.0 to 1.0
                  • Default: 0.4
                  • Description: The friction value for entities traversing the block.
              • geometry:
                • Type: string
                  • Default: none
                  • Description: The geometry identifier of the block.
                • Type: object
                  • Description: The geometry of the block with bone visbility filters
                    • identifier
                      • Type: string
                        • Default: none
                        • Description: The geometry identifier of the block.
                    • bone_visibility:
                      • Type: object
                        • Description: An object containing the bone visibility filters for the block.
                          • bone_name:
                            • Type: string
                              • Default: none
                              • Description: A molang string dictating whether the bone is visible.
                            • Type: boolean
                              • Default: none
                              • Description: Whether the bone is visible.
              • light_emission:
                • Type: integer
                  • Range: 0 to 15
                  • Default: 0
                  • Description: The amount of light emitted by the block.
              • light_dampening:
                • Type: integer
                  • Range: 0 to 15
                  • Default: 15
                  • Description: The amount of light dampened by the block as it passes through.
              • material_instances:
                • Type: object
                  • Description: An object containing the material instances for the block.
                    • key:
                      • Type: object
                        • Description: The default material instance for the block. Other globs or specific instances can be used.
                          • texture:
                            • Type: string
                              • Default: the name of the custom block
                              • Description: The texture resource path of the block.
                          • render_method:
                            • Type: string
                              • Default: alpha_test
                              • Description: The render method used for the block.
                          • face_dimming:
                            • Type: boolean
                              • Default: false
                              • Description: Whether face dimming is enabled for the block.
                          • ambient_occlusion:
                            • Type: boolean
                              • Default: false
                              • Description: Whether ambient occlusion is enabled for the block.
              • place_air:
                • Type: boolean
                  • Default: true
                  • Description: Whether the block should place air to prevent double placement.
              • placement_filter:
                • Type: object
                  • Description: An object containing the placement filter for the block.
                    • conditions:
                      • Type: array
                        • Description: An array of conditions that must be met for the block to be placed.
                          • allowed_faces:
                            • Type: array
                              • Description: An array of faces that the block can be placed on.
                                • items:
                                  • Type: string
                                    • Range: up, down, north, south, east, west
                                    • Description: A face that the block can be placed on.
                                • block_filter:
                                  • Type: array
                                    • Description: An array of blocks or true molang queries that the block can be placed on.
                                      • items:
                                        • Type: string
                                          • Description: A block that the block can be placed on.
                                            • Type object
                                              • Description: Holds a true molang query that the block can be placed on.
                                                • tags:
                                                  • Type: array
                                                    • Description: A true molang query that the block can be placed on.
              • selection_box:
                • Type: object
                  • origin:
                    • Type: array
                      • Default: Inferred from overridden block
                      • Description: An array of x, y, and z origin values
                      • Range: Must be in range [-8, 0, -8] to [8, 16, 8], inclusive
                        • items:
                          • Type: float
                            • Default: Inferred from overridden block
                            • Description: An origin value for a single axis
                  • size:
                    • Type: array
                      • Default: Inferred from overridden block
                      • Description: An array of x, y, and z size values
                        • items:
                          • Type: float
                            • Default: Inferred from overridden block
                            • Description: An size value for a single axis
                  • Range: Addittion of origin and size must be in range [-8, 0, -8] to [8, 16, 8], inclusive.
              • tags:
                • Type: array
                  • Description: An array of tags associated with the block.
                    • items:
                      • Type: string
              • transformation:
                • Type: object
                  • Description: Translation, scale, and rotation values to apply to the block.
                    • scale
                      • Type: array
                        • Default: [1, 1, 1]
                        • Description: An array of x, y, and z scale values
                          • items:
                            • Type: float
                              • Default: 1
                              • Description: A scale value for a single axis
                    • translation:
                      • Type: array
                        • Default: [0, 0, 0]
                        • Description: An array of x, y, and z translation values
                          • items:
                            • Type: float
                              • Default: 0
                              • Description: A translation value for a single axis
                    • rotation
                      • Type: array
                        • Default: [0, 0, 0]
                        • Description: An array of x, y, and z rotation values in increments of 90 degrees (e.g. [90, -180, 0])
                          • items:
                            • Type: integer
                              • Range: 0, 90, 180, & 270
                              • Default: 0
                              • Description: A rotation value for a single axis
              • unit_cube:
                • Type: boolean
                  • Default: false
                  • Description: Whether a unit cube is to be used with tessellation.
              • creative_category:
                • Type: string
                  • Default: building_blocks
                  • Description: The creative category to place the block in.
                  • Range: See Menu Categories on the Bedrock Wiki.
              • creative_group:
                • Type: string
                  • Default: none
                  • Description: The creative group to place the block in.
                  • Range: See Menu Groups on the Bedrock Wiki.
              • included_in_creative_inventory:
                • Type: boolean
                  • Default: true
                  • Description: Whether the block is included in the creative inventory.
              • only_override_states:
                • Type: boolean
                  • Default: false
                  • Description: Whether the block should only override the states specified in state_overrides.
              • state_overrides:
                • Type: object
                  • Description: An object containing state overrides for the block.
                    • property1=value1,property2=value2,...:
                      • Type: object
                        • Description: An override for a specific block state. Possible states are listed in Geyser's Block Mappings
                        • Accepts all of the same properties as a block definition except creative_category, creative_group, included_in_creative_inventory, only_override_states, and state_overrides.

Geyser extensions

In this example, we will create a custom block that overrides the vanilla redstone dot. This block will be placed on top of a block and will emit a visible redstone signal when powered.

First, create a class that implements Geyser's Extension class:

public class RedstoneDot implements Extension {
    //...
}

Next, create a method to register your blocks in the GeyserDefineCustomBlocksEvent:

public class RedstoneDot implements Extension {
    @Subscribe
    public void onDefineCustomBlocks(GeyserDefineCustomBlocksEvent event) {
        //...
    }
}

Build the CustomBlockComponents, CustomBlockData, and list of CustomBlockPermutation (if needed) for the block:

public class RedstoneDot implements Extension {
    @Subscribe
    public void onDefineCustomBlocks(GeyserDefineCustomBlocksEvent event) {
        BoxComponent selectionBox = new BoxComponent(-5, 0, -5, 10, 1f, 10);

        CustomBlockComponents components = CustomBlockComponents.builder()
                .collisionBox(BoxComponent.emptyBox())
                .selectionBox(selectionBox)
                .geometry(new GeometryComponentBuilder()
                    .identifier("geometry.amberichu.redstone_dot")
                    .build())
                .lightEmission(0)
                .lightDampening(0)
                .friction(1f)
                .build();

        CustomBlockData redstoneDot = CustomBlockData.builder()
                .name("redstone_dot")
                .intProperty("POWER_PROPERTY", IntStream.range(0, 16).boxed().toList())
                .components(components)
                .permutations(createRedstoneDotPermutations())
                .build();

        // ...
    }

    private List<CustomBlockPermutation> createRedstoneDotPermutations() {
        List<CustomBlockPermutation> permutations = new ArrayList<>();
        for (int power = 0; power < 16; power++) {
            String texture = "amberichu.redstone_dot" + power;
            MaterialInstance invisMaterialInstance = MaterialInstance.builder()
                        .texture("amberichu.invisible")
                        .renderMethod("alpha_test")
                        .faceDimming(false)
                        .ambientOcclusion(false)
                        .build();
            CustomBlockComponents components = CustomBlockComponents.builder()
                    .materialInstance("up", MaterialInstance.builder()
                        .texture(texture)
                        .renderMethod("alpha_test")
                        .faceDimming(false)
                        .ambientOcclusion(false)
                        .build())
                    .materialInstance("down", invisMaterialInstance)
                    .materialInstance("north", invisMaterialInstance)
                    .materialInstance("south", invisMaterialInstance)
                    .materialInstance("east", invisMaterialInstance)
                    .materialInstance("west", invisMaterialInstance)
                    .build();
            String condition = String.format("query.block_property('%s') == %d", POWER_PROPERTY, power);
            permutations.add(new CustomBlockPermutation(components, condition));
        }
        return permutations;
    }
}

Finally, register the custom block, block state overrides, and block item overrides:

public class RedstoneDot implements Extension {
    @Subscribe
    public void onDefineCustomBlocks(GeyserDefineCustomBlocksEvent event) {
        BoxComponent selectionBox = new BoxComponent(-5, 0, -5, 10, 1f, 10);

        CustomBlockComponents components = CustomBlockComponents.builder()
                .collisionBox(BoxComponent.emptyBox())
                .selectionBox(selectionBox)
                .geometry(new GeometryComponentBuilder()
                    .identifier("geometry.amberichu.redstone_dot")
                    .build())
                .lightEmission(0)
                .lightDampening(0)
                .friction(1f)
                .build();

        CustomBlockData redstoneDot = CustomBlockData.builder()
                .name("redstone_dot")
                .intProperty("POWER_PROPERTY", IntStream.range(0, 16).boxed().toList())
                .components(components)
                .permutations(createRedstoneDotPermutations())
                .build();
        
        event.register(redstoneDot);
        event.registerItemOverride("minecraft:redstone_wire", redstoneDot);

        for (int power = 0; power < 16; power++) {
            String javaIdentifier = String.format("minecraft:redstone_wire[east=none,north=none,power=%d,south=none,west=none]", power);
            event.registerOverride(javaIdentifier, redstoneDot.blockStateBuilder()
                    .intProperty("POWER_PROPERTY", power)
                    .build());
        }
    }

    private List<CustomBlockPermutation> createRedstoneDotPermutations() {
        List<CustomBlockPermutation> permutations = new ArrayList<>();
        for (int power = 0; power < 16; power++) {
            String texture = "amberichu.redstone_dot" + power;
            MaterialInstance invisMaterialInstance = MaterialInstance.builder()
                        .texture("amberichu.invisible")
                        .renderMethod("alpha_test")
                        .faceDimming(false)
                        .ambientOcclusion(false)
                        .build();
            CustomBlockComponents components = CustomBlockComponents.builder()
                    .materialInstance("up", MaterialInstance.builder()
                        .texture(texture)
                        .renderMethod("alpha_test")
                        .faceDimming(false)
                        .ambientOcclusion(false)
                        .build())
                    .materialInstance("down", invisMaterialInstance)
                    .materialInstance("north", invisMaterialInstance)
                    .materialInstance("south", invisMaterialInstance)
                    .materialInstance("east", invisMaterialInstance)
                    .materialInstance("west", invisMaterialInstance)
                    .build();
            String condition = String.format("query.block_property('%s') == %d", POWER_PROPERTY, power);
            permutations.add(new CustomBlockPermutation(components, condition));
        }
        return permutations;
    }
}