Pocket Instruments

# Pocket Instruments

**Fancy pocket watches you actually pull out and hold.**

Forget flat sprites. Every watch in Pocket Instruments is a real 3D object that dangles from your hand on a little chain. It swings when you walk, swings harder when you sprint or jump, and settles with a couple of gentle swings when you stop. Pull one out and it lifts into view, the lid pops open with a small click, and the second hand keeps ticking away.

Everything on the dial is live: the time, the moon, the weather, your altitude and more.

## The four instruments

**Time Watch** (gold case, cream dial, tiny moon window)

- **Clock:** hour and minute hands, a second hand that ticks once a real second, a digital readout and a day counter
- **Moon:** the current moon phase, its name, and how many nights until the next full moon

**Weather Watch** (copper case, green patina trim)

- **Conditions:** what the weather is doing where you stand: clear, rain, snow, thunderstorm, or overcast in a biome too dry for rain
- **Forecast:** a sweeping needle and text like "Rain in ~12 min", "Clearing in ~4 min" or "Clear for ~35 min"

**Altimeter** (iron case, dark dial, one big needle)

- **Altitude:** a gauge needle, your Y level, and your height above or below sea level
- **Layers:** a slice through the world with a marker at your height, the layer you're in, your depth below the surface, and the distance to the world's floor and ceiling

**Grand Complication** (larger gold and diamond case, sub-dials, a faint glint)

Every page above, plus:

- **Position:** X, Y, Z, the way you're facing, and an arrow pointing to world spawn. It spins wherever a vanilla compass would.
- **Biome:** a little window in the biome's real sky and grass colours, plus its name, temperature and precipitation
- **Light:** block light and sky light at your feet, and a warning when block light is 0, the level where hostile mobs can spawn
- **Stopwatch:** start, stop and reset with its own keys

It's crafted with netherite, so it won't burn up in fire or lava.

In places with no day cycle, such as the Nether and the End, the hands spin erratically and the time reads --:--. Places with no moon or weather say so on the dial.

## Features

- Truly round 3D models with a hinged lid, winding crown, chain and glass crystal
- Hangs from your hand in first and third person, in either hand or both, and other players' watches hang and swing too
- Pendulum physics driven by how you really move: walking, sprinting, jumping and turning
- Live dials everywhere: in hand, in your hotbar and inventory, on the ground and in item frames
- Watches in item frames or on the ground read altitude, light and biome from where they are
- A proper ticking second hand, even on the tiny hotbar icon
- A faintly luminous dial, so you can read it in the dark (you can turn this off)

## Controls

- **Right-click:** next page
- **Sneak + right-click:** previous page

This works from either hand, in the air or on any block without its own interaction. Chests and doors still work normally.

Optional keys, all unbound by default, are in Options > Controls > Pocket Instruments:

- Cycle Pocket Instrument page
- Stopwatch start / stop
- Stopwatch reset

## Crafting

Recipes unlock in your recipe book when you pick up the key ingredient.

- **Time Watch:** chain in the top middle; gold ingot, clock, gold ingot across the middle; glass pane in the bottom middle
- **Weather Watch:** the same shape, with copper ingots and a lightning rod
- **Altimeter:** the same shape, with iron ingots and a compass
- **Grand Complication:** top row diamond, Time Watch, diamond; middle row Weather Watch, netherite ingot, Altimeter; bottom row diamond, echo shard, diamond

Recipes are plain JSON and use common Forge tags where they exist, so a data pack can change them.

## Settings

**Your own settings** are in `config/pocketinstruments-client.toml`. Save the file while the game is running and changes apply within about a second.

- Hold position, angle and size, in first and third person
- Show or hide your arm, and raise or lower the third-person arm pose
- Swing strength, damping, idle drift and maximum angle
- 12 or 24 hour time, the luminous dial, and an optional small text readout beside the hotbar
- An optional soft tick sound (off by default), its volume, and the click sounds

**World and server settings** are in `serverconfig/pocketinstruments-server.toml` inside each world, and are copied to everyone who joins.

- Forecast precision: EXACT ("~12 min") or VAGUE ("soon", "a while")
- The mob spawn warning on or off
- A switch for every page type, for anyone who finds one too revealing

## For modpack makers

- You're welcome to include Pocket Instruments in modpacks.
- No Mixins, no coremods, no other mods needed, and no changes to vanilla behaviour.
- It never connects to the internet. Its only network traffic uses Minecraft's own connection: a small forecast packet about once a second to players holding a watch with a Forecast page, and a packet when someone uses the cycle key.
- All textures are on one sheet for resource packs: `assets/pocketinstruments/textures/watch/sheet.png`
- All text is in the language file, ready for translation.
- In testing, eleven watches on screen at once added about 1 ms per frame.

## Compatibility

- Minecraft 1.20.1 with Forge. Built and tested on Forge 47.4.10. Other 47.x builds should work but haven't been tested.
- Install it on both the client and the server.
- This is a first release. It has been tested in singleplayer and with automated checks in a dedicated-server environment, but not yet in a real multiplayer session, so reports from real servers are very welcome.
- Not yet tested with Sodium, Iris or shader packs.
- Curios: the watches are tagged for its charm slot. This is experimental and untested.

## FAQ

**Does it need to be on the server?**
Yes, on both the client and the server.

**Why does the Light page warn about mobs in broad daylight?**
It checks block light at your feet, and sunlight doesn't count as block light. A spot showing the warning has no torch or other light source reaching it, so hostile mobs can spawn there once it gets dark.

**The watch is too big or in my way. Can I move it?**
Yes. Change `scale`, `handX` and `handY` in the client config, and save the file while you play.

**Can I turn off the swinging?**
Yes. Set `strength` and `idleDrift` to 0 in the `sway` section of the client config.

**Does it change vanilla clocks or compasses?**
No. Vanilla items work exactly as before.

## Known limitations

- The Forecast page shows -- on a watch in an item frame or on the ground, because the server only sends forecasts to players holding a forecast watch.
- The stopwatch lives on your own game, is shared by all your Grand Complications, and resets when you close the game.
- The pull-out animation doesn't replay when you swap between two identical watches.