whatisgithub

What is pebble?

thebriangao/pebble — explained in plain English

Analysis updated 2026-05-18

84SwiftAudience · vibe coderComplexity · 3/5Setup · moderate

In one sentence

A free, open-source macOS game that recreates Minecraft: Java Edition's core gameplay from scratch in native Swift, with no outside engine.

Mindmap

mindmap
  root((pebble))
    What it does
      Recreates Minecraft gameplay
      Custom Metal renderer
      Synthesized audio
    Tech stack
      Swift
      Metal
    Use cases
      Play a native macOS sandbox game
      Study a from-scratch game engine
    Audience
      Vibe coders

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Play a Minecraft-like sandbox game natively on a Mac.

USE CASE 2

Study how a full game engine and renderer is built from scratch in Swift and Metal.

USE CASE 3

Explore procedurally generated structures like villages and strongholds.

What is it built with?

SwiftMetalXcode

How does it compare?

thebriangao/pebbleeasychen/markmarkjoeseesun/qmprompter
Stars848587
LanguageSwiftSwiftSwift
Setup difficultymoderateeasymoderate
Complexity3/51/53/5
Audiencevibe coderwritergeneral

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Requires macOS 14+, an Apple silicon Mac recommended, and Xcode command-line tools.

No license information is provided in the available documentation.

So what is it?

Pebble is a free, open-source game for macOS that works like Minecraft: Java Edition. It was built entirely from scratch in about 45,000 lines of Swift code, with no outside libraries or game engines. It runs natively on macOS 14 and above, and the developers recommend an Apple silicon Mac for the best experience. The game covers the full Minecraft progression: you can mine, craft, brew potions, enchant items, and explore three separate dimensions (the overworld, nether, and end). It includes 879 block types, over 1,000 items, 63 biomes, and more than 55 different enemies with their own movement and behavior patterns. Structures like villages, strongholds, ocean monuments, and ancient cities generate in the world the same way they do in the original game. One unusual aspect is how the game handles audio. Instead of bundling sound files, Pebble creates every sound in real time using synthesized oscillators and filters, including ambient music, jukebox tracks, and all in-game effects. The visual side is similarly custom: the renderer is written directly in Apple's Metal graphics API, with effects like ambient occlusion, volumetric light, and soft shadows available as an optional ultra graphics setting. Installing the game requires macOS 14 and the Xcode command-line tools. After cloning the repository and running a single install script, the game compiles and places itself in your Applications folder. A built-in test command runs 456 regression checks against known-good outputs to confirm the engine is working correctly. Pebble is in beta, and the developers are actively asking for bug reports. The project has no connection to Mojang or Microsoft, uses no original Minecraft code or assets, and ships with the third-party Faithful 32x texture set, which is credited separately. It is singleplayer only for now.

Copy-paste prompts

Prompt 1
Walk me through cloning and installing Pebble on my Mac.
Prompt 2
Explain how Pebble synthesizes all its game audio in real time instead of using sound files.
Prompt 3
Describe how Pebble's Metal renderer implements ambient occlusion and volumetric light.
Prompt 4
What regression tests does Pebble run to confirm the engine is working?

Frequently asked questions

What is pebble?

A free, open-source macOS game that recreates Minecraft: Java Edition's core gameplay from scratch in native Swift, with no outside engine.

What language is pebble written in?

Mainly Swift. The stack also includes Swift, Metal, Xcode.

What license does pebble use?

No license information is provided in the available documentation.

How hard is pebble to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is pebble for?

Mainly vibe coder.

Open on GitHub → Ask about another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.