Ruststone

Ruststone is a Minecraft Java Edition 1.8.9-targeted Rust client built with Bevy. The long-term goal is playable PvP (including Bedwars-style gameplay), with protocol compatibility first and feature-completeness in iterations.

Current progress

Core gameplay and rendering

• 20 TPS fixed-step local simulation with client-side prediction + reconciliation.
• Basic movement/camera flow, collisions, sneaking, sprinting, jumping.
• World/chunk decoding and meshing with async mesh generation.
• Chunk metadata/state decode kept end-to-end (id + meta) and used in render/collision paths.
• Block texture atlas rendering, water transparency improvements, biome tint support.
• SSR-based water reflections with skybox fallback, wave distortion, and runtime tuning controls.
• Water reflection tuning controls (strength, near-boost, optional blue tint, wave strength/speed).
• State-aware texture selection for metadata variants (e.g. acacia/dark-oak logs & leaves, flower variants).
• Non-cube rendering for slabs and stairs (metadata-driven orientation/half) instead of full-cube fallback.
• Custom model rendering + collision boxes for common special blocks: farmland, ladder, snow layer, cactus, soul sand, trapdoor, carpet, rails, doors, fence gates, and cobble/mossy walls.
• Manual/engine culling toggles, render distance controls, wireframe and performance overlays.

Networking and gameplay loop

• Connect/login/play loop against 1.8.9 servers.
• Offline username flow plus Prism-backed online-mode auth.
• Chunk + block updates wired into world state and remeshing.
• Local player movement send + server correction handling (including large-teleport snap path).
• Server-driven gamemode, abilities, world time, health, hunger, and XP sync into local state/HUD.
• Remote entity scaffolding for players, mobs, objects, dropped items and XP orbs.
• Remote player name/skin ingestion and basic mob rendering coverage for common PvP-relevant mobs.
• Entity click interactions (attack/interact), knockback velocity ingest, item use in air.
• Chat, chat tab-complete, disconnect reasons, health/death/respawn flow, hotbar drop (Q, Ctrl+Q).
• Title, subtitle, action bar, tab-list header/footer, scoreboard sidebar, and world sound ingest are wired.
• Local block placement guard prevents placing into the local player collider.
• Movement collision supports slab/stair shapes and includes vanilla-style step-up (0.6) for walking up stairs.
• Movement collision now includes many custom/non-cube block shapes used in world meshing (not just slab/stair).

UI (egui)

• Connect screen, chat, pause menu, debug menu, death screen.
• Crosshair + block break progress indicator.
• HUD bars for health, hunger, and experience.
• Scoreboard sidebar, title/subtitle/action-bar overlays, and tab-list header/footer.
• Survival inventory/hotbar window scaffolding with server-synced item stacks.
• Inventory item textures loaded from the client texture pack.
• Debug overlay can show looked-at block details (position, id/state/meta, model kind, registry key, collision boxes).
• Chat tab-complete and Prism account picker on the connect screen.
• Persistent options UI for rendering, water, sound, HUD, and system settings.
• Inventory interactions implemented for common survival actions:
  • left/right click
  • shift-click
  • number-key swap
  • Q / Ctrl+Q drop
  • double-click collect
  • outside click drop

Packet support status (Minecraft 1.8.9 / protocol 47)

Legend:

• Implemented: encoded/decoded and used by client logic.
• Partial: parsed but currently ignored or only partly used.
• Not implemented: currently not handled by Ruststone logic.

Handshake/Login packets

State	Direction	Packet	Status	Notes
Handshake	Serverbound	Handshake	Implemented	Sent during connect sequence.
Login	Serverbound	LoginStart	Implemented	Username login start.
Login	Serverbound	EncryptionResponse	Implemented	Sent when server requests encryption (online mode).
Login	Clientbound	SetInitialCompression	Implemented	Compression threshold applied.
Login	Clientbound	LoginSuccess_String / LoginSuccess_UUID	Implemented	Transition to play state.
Login	Clientbound	LoginDisconnect	Implemented	Reported to UI as connect failure.
Login	Clientbound	EncryptionRequest	Implemented	Online-mode auth via Prism account selection.

Serverbound Play packets

ID	Packet	Status	Notes
0x00	KeepAliveServerbound_VarInt	Implemented	Reply path for keepalive.
0x01	ChatMessage	Implemented	Chat send.
0x02	UseEntity_Handsfree	Implemented	Attack/interact entity packets.
0x03	Player	Implemented	Ground-only movement heartbeat path.
0x04	PlayerPosition	Implemented	Position-only movement send path.
0x05	PlayerLook	Implemented	Look-only movement send path.
0x06	PlayerPositionLook	Implemented	Full position+look movement send path.
0x07	PlayerDigging_u8	Implemented	Start/cancel/finish dig + drop item/stack actions.
0x08	PlayerBlockPlacement_u8_Item	Implemented	Place block + right-click-air item use path.
0x09	HeldItemChange	Implemented	Hotbar select + wheel/number keys.
0x0A	ArmSwing_Handsfree	Implemented	Left-click swing animation packet.
0x0B	PlayerAction	Implemented	Sneak/sprint action toggles.
0x0C	SteerVehicle	Not implemented
0x0D	CloseWindow	Implemented	Inventory window close.
0x0E	ClickWindow_u8	Implemented	Survival inventory interaction path.
0x0F	ConfirmTransactionServerbound	Implemented	Rejection-ack flow.
0x10	CreativeInventoryAction	Not implemented
0x11	EnchantItem	Not implemented
0x12	SetSign	Not implemented
0x13	ClientAbilities_f32	Implemented	Flight ability flags/speeds sent when toggled.
0x14	TabComplete_NoAssume	Implemented	Chat UI requests server tab-complete suggestions.
0x15	ClientSettings_u8_Handsfree	Implemented	Sent immediately after JoinGame using requested view distance.
0x16	ClientStatus	Implemented	Respawn action.
0x17	PluginMessageServerbound	Not implemented
0x18	SpectateTeleport	Not implemented
0x19	ResourcePackStatus	Not implemented

Clientbound Play packets

ID	Packet	Status	Notes
0x00	KeepAliveClientbound_VarInt	Implemented	Immediate reply sent.
0x01	JoinGame_i8	Implemented	Local player entity id wiring.
0x02	ServerMessage_Position	Implemented	Chat ingest (ServerMessage_* variants).
0x03	TimeUpdate	Implemented	World time sync updates HUD/render time state.
0x04	EntityEquipment_u16	Implemented	Remote player held-item is visualized (slot 0); armor slots TODO.
0x05	SpawnPosition	Not implemented
0x06	UpdateHealth	Implemented	Health/food/death state.
0x07	Respawn_Gamemode	Implemented	Also handles hashed-seed / NBT / world-name respawn variants.
0x08	TeleportPlayer_NoConfirm	Implemented	Also handles protocol variants.
0x09	SetCurrentHotbarSlot	Implemented	Hotbar slot sync.
0x0A	EntityUsedBed	Not implemented
0x0B	Animation	Implemented	Remote animation events parsed and applied to remote visuals.
0x0C	SpawnPlayer_i32_HeldItem	Implemented	Also handles other spawn player variants.
0x0D	CollectItem_nocount	Partial	Currently despawns collected item to avoid ghost entities (no fly-to animation yet).
0x0E	SpawnObject_i32_NoUUID	Implemented	Spawned as typed placeholder visuals.
0x0F	SpawnMob_u8_i32_NoUUID	Implemented	Spawned as typed placeholder visuals.
0x10	SpawnPainting_NoUUID	Not implemented
0x11	SpawnExperienceOrb_i32	Implemented	Spawned as placeholder orb visuals.
0x12	EntityVelocity	Partial	Local player knockback velocity applied; remote entity velocity is decoded but not fully simulated.
0x13	EntityDestroy	Implemented	Also handles EntityDestroy_u8.
0x14	Entity	Not implemented
0x15	EntityMove_i8	Implemented	Also handles alternate move variants.
0x16	EntityLook_VarInt	Implemented	Also handles alternate look variants.
0x17	EntityLookAndMove_i8	Implemented	Also handles alternate variants.
0x18	EntityTeleport_i32	Implemented	Also handles alternate variants.
0x19	EntityHeadLook	Implemented	Remote player head yaw is applied independently from body yaw.
0x1A	EntityStatus	Partial	Hurt animation mapped for common status codes.
0x1B	EntityAttach_leashed	Not implemented
0x1C	EntityMetadata	Implemented	Parsed for pose flags (sneak) and dropped-item labels from stack metadata.
0x1D	EntityEffect	Partial	Speed/Jump Boost applied to local simulation state.
0x1E	EntityRemoveEffect	Partial	Clears Speed/Jump Boost state for local player.
0x1F	SetExperience	Implemented	Experience bar / level / total XP sync to HUD state.
0x20	EntityProperties	Partial	Local movement speed is derived from generic.movementSpeed; most other attributes are ignored.
0x21	ChunkData_NoEntities_u16	Implemented	Handled via ChunkData decode path.
0x22	MultiBlockChange_VarInt	Implemented	Also handles MultiBlockChange_u16.
0x23	BlockChange_VarInt	Implemented	Also handles BlockChange_u8.
0x24	BlockAction	Not implemented
0x25	BlockBreakAnimation	Not implemented
0x26	ChunkDataBulk	Implemented	Chunk ingest/decode path.
0x27	Explosion	Partial	Explosion sound is played; physics/particle effects are not yet applied.
0x28	Effect	Partial	Common auxiliary effects are mapped to sounds only.
0x29	NamedSoundEffect_u8_NoCategory	Implemented	Also handles named-sound variants with category fields.
0x2A	Particle_VarIntArray	Not implemented
0x2B	ChangeGameState	Partial	Gamemode-change reason is handled; most other reasons are ignored.
0x2C	SpawnGlobalEntity_i32	Not implemented
0x2D	WindowOpen	Implemented	Inventory windows + variants.
0x2E	WindowClose	Implemented	Inventory close sync.
0x2F	WindowSetSlot	Implemented	Inventory slot delta updates.
0x30	WindowItems	Implemented	Inventory bulk updates.
0x31	WindowProperty	Not implemented
0x32	ConfirmTransaction	Implemented	Reject/ack path wired.
0x33	UpdateSign	Not implemented
0x34	Maps_NoTracking	Not implemented
0x35	UpdateBlockEntity	Partial	Parsed, ignored.
0x36	SignEditorOpen	Not implemented
0x37	Statistics	Not implemented
0x38	PlayerInfo	Implemented	Name/UUID registry updates.
0x39	PlayerAbilities	Implemented	Syncs mayfly/flying + speed values into local status.
0x3A	TabCompleteReply	Implemented	Suggestions feed the chat autocomplete UI.
0x3B	ScoreboardObjective	Implemented	Objective create/update/remove wired into sidebar state.
0x3C	UpdateScore	Implemented	Score entries update the sidebar scoreboard.
0x3D	ScoreboardDisplay	Implemented	Sidebar display slot is tracked.
0x3E	Teams_u8	Implemented	Team prefixes/suffixes and membership update scoreboard state.
0x3F	PluginMessageClientbound	Not implemented
0x40	Disconnect	Implemented	Disconnect reason is surfaced to the connect/chat UI.
0x41	ServerDifficulty	Not implemented
0x42	CombatEvent	Not implemented
0x43	Camera	Not implemented
0x44	WorldBorder	Not implemented
0x45	Title_notext_component	Implemented	Title/subtitle/action-bar/timing variants are displayed.
0x46	SetCompression	Not implemented (play)	Compression is handled during login (SetInitialCompression).
0x47	PlayerListHeaderFooter	Implemented	Tab-list header/footer text is displayed.
0x48	ResourcePackSend	Not implemented
0x49	EntityUpdateNBT	Not implemented

Known gaps

• Breaking indicator is currently a local estimate and not yet server-confirmed timing.
• Dropped item labels currently rely on metadata parsing plus static fallback naming (not full translation/NBT naming parity).
• Inventory drag-splitting (mode 5) not implemented yet.
• Stair corner shape rendering/collision (inner/outer) is still simplified; straight/top/bottom variants are implemented.
• Block model/collider coverage is still incomplete for full vanilla parity (many high-impact special cases are now implemented, but not every block/state).
• Mob rendering coverage is expanded (player, zombie, skeleton, creeper, pig, sheep, cow, enderman), but full vanilla entity set is not done yet.
• Many play packets are still intentionally unimplemented (see matrix above).
• Protocol support target is currently 1.8.9 only.

Shipping Build (Single Binary)

• Runtime asset lookup is unified via RUSTSTONE_ASSETS_ROOT.
• Bevy dynamic_linking is disabled in workspace crates so release builds can be shipped as a single executable.

Build commands

• Linux/macOS release build:
  • cargo build -p rs-client --release
• Windows build from Linux (GNU toolchain target):
  • rustup target add x86_64-pc-windows-gnu
  • install a MinGW-w64 cross linker (x86_64-w64-mingw32-gcc)
  • cargo build -p rs-client --release --target x86_64-pc-windows-gnu

Notes:

• ruststone_options.toml and Prism accounts.json remain external runtime files.
• For Windows MSVC targets (x86_64-pc-windows-msvc) you need the MSVC linker/toolchain (typically from a Windows build environment).

Credits and attribution

• Networking/protocol foundation and architecture references were adapted from Leafish and related Steven/Stevenarella lineage:
  • https://github.com/Lea-fish/Leafish
  • Leafish is dual-licensed (MIT / Apache-2.0).
• Binary greedy meshing integration was built from local adaptation study of:
  • binary_greedy_mesher_demo in this workspace
  • and its referenced algorithm resources, including:
    • https://github.com/cgerikj/binary-greedy-meshing

Please keep upstream license and attribution requirements when reusing or redistributing derived code.