# Family Island *A little world, grown into a place for the whole family.* Family Island started as a little world the four of us have been building: you walk around it, build things on your own land, and keep your books on bookcases you visit by walking up to them. Family Island is where that world is going next: an island in the middle of the sea with a home for every family. You visit each other through your front doors, write in each other's guestbooks, water each other's gardens, and send letters by a courier who walks the long way round. This document is the plan. It starts with **what exists today**, then lays out **the steps from here to the island**, one at a time. The early steps are worked out in detail. The later ones are sketches, and that is fine: they get filled in as we get closer to them. ## How to read this First comes a tour of the world as it is today, with the controls and everything you can build. Then comes **the road to the island**: eleven steps, each with a stamp saying how far along it is, and a checklist of what it needs. Ticked boxes are finished. The rest is what is coming. This booklet is a living plan. It changes as the game does, and family ideas are very welcome. The best ones end up as new boxes on a checklist. > **Builder's notes** > > **This file is the source of truth.** It lives at `docs/FAMILY-ISLAND.md`. > The illustrated booklet (`deploy/island/index.html`) reads it every time it > opens and draws itself from it, so changing the plan means editing this file > and nothing else. It is served on the island's own address, > `island.twinsparks.com`, from a folder of its own; the deploy copies this > file and the game's sprite sheets into that folder beside the page. > > **This file is read by the family.** Family Island is its own site, and the > family must not learn that anything else runs alongside it. Keep this file > free of the other apps, their address, their accounts and their roles. The > booklet belongs on the island's own address, not anywhere else. > > A few conventions make the booklet work. They are invisible on GitHub and in > plain editors, and only the booklet pays attention to them: > > - `` names game sprites to draw at that spot, using the names > in `deploy/site/tiles.json`. `person:aaron` draws one of the four people, > and `look:7` draws the character the wardrobe would pick from the number 7. > `frame` draws a picture frame, and `sketch:Some name` draws a dashed > placeholder for art that does not exist yet. > - `**Status:**` at the start of a step is drawn as a stamp. The statuses are > **Done**, **Building now**, **Next up**, **Planned**, **Sketch** and > **Someday**. > - A blockquote that starts with **Builder's notes** is folded away in the > booklet under "For the builder". That is where the tables, the code and the > open questions go, so the family gets the fun part and the details are one > click away. > - `- [x]` and `- [ ]` are checklists. The booklet draws them as ticked and > unticked boxes, which makes the wishlists double as a to-do list. ## Where we are today The world is a tall tower of nine floors stacked on top of each other, from a damp cellar at the bottom to a floor of falling stars at the top. Each of the four of us has a plot of land on every floor, marked out with dashed fences, and in the middle of each floor is a shared cobbled plaza that belongs to everyone. Stairs in the plaza take you up and down. **The floors, bottom to top:** | Floor | Name | What it is like | | --- | --- | --- | | -1 | The Cellar | Cool and quiet. Something is dripping. | | 0 | The Commons | Where everyone comes in. | | 1 | Upper Hall | Floorboards and long afternoon light. | | 2 | The Gallery | Your footsteps echo up here. | | 3 | The Orchard | Somebody has been growing things. | | 4 | The Roost | Low beams. Mind your head. | | 5 | Cloudline | The ground is a long way down. | | 6 | The Observatory | The sky has gone dark and enormous. | | 7 | Starfall | There is nothing above this. | ### Getting around | To do this | Press | On a phone | | --- | --- | --- | | Walk | Arrow keys or WASD | The d-pad | | Run (and stop running) | Shift | The Run button | | Open a bookcase, take the stairs, open a door | E, Enter or Space | The action button | | Switch between exploring and building | B (or right-click to stop building) | Build / Explore | | Leave | Escape | The way-out button | You can face eight ways, so you can walk up to a bookcase on the diagonal. Full screen hides everything else on the page, and the floor's name sits in the top corner so you always know where you are. ### Bookcases Bookcases are why the world exists. Each one shimmers and glows a little after dark. Walk up to one and press E, and its shelves open over the world. The world stays dimmed underneath, and when you close the bookcase you are standing exactly where you were. Dragging books around, finishing them and logging your reading all work from inside the world. You can open anybody's bookcase to see what they are reading, but only your own books are yours to move. ### Building Press B to build. You can build anywhere on your own land that you can see. The plaza and other people's land are off limits. The **left button** puts down whatever is in your hand; hold it and drag to paint a whole row of floor in one stroke. **X** (or the Take button) takes away what you are pointing at, and the **right button** is "done building" and takes you back to exploring. On a phone, a tap places and a long press takes away. Every tile has room for a **floor** underneath and **one thing** on top, so a rug can go under a chair. Things that face a direction turn with R. Your ten favourite blocks live in the slots along the bottom: keys 1 to 0, or roll the **mouse wheel** to move along them. The full menu opens with I. Like something you see? **Middle-click** it and it goes into the slot you are on, turned the way it was, ready to put down again. The menu has a tab for each set of blocks, and a **Special** tab for the things that do something: your bookcases (and a button to make a new one), picture frames, the wardrobe, pets, stairs, and the spot where you come in. Staircases can be built too. Put one down and its other end appears on the floor above (or below). Pick it up from either end and both ends go. ### Eight sets of blocks There are eight sets of blocks, each in its own tab of the menu, and any of them can go on any floor. **The Orchard:** wood, soil and leaves. **Pink Skies:** cloudstone, pearl and blossom, for the floors above the clouds. **Cozy Cottage:** brick, pine and wool. This is the first set made for making somewhere to *live*. **The Parlour:** walnut, papered walls and velvet, for the living room, the bedroom and the nursery. The curtains open and shut, and the wall clock tells the world's time. **Kitchen and Bath:** counters that join up like walls, a range with a kettle on, and a clawfoot bath full of bubbles. **The Library:** oak panelling, tall shelves, green leather and brass, and a grandfather clock that keeps the world's time. **The Front Yard:** white pickets, a mown lawn, the washing line, and everything else outside the front door. **Seaside:** sand and water, a dock, a lighthouse, and a striped beach hut. This is the island's own set. Every set has floors to lay (each with eight versions, so no two patches look alike), and the sets with walls have walls that turn corners and meet any other set's walls exactly, windows, and doors or gates that really open and close. ### Things that are alive - **Day and night.** One game hour passes every real minute, so a whole day goes by in 24 minutes. It is the same time for everyone. Lanterns, lamps, fireplaces and the fish tank light up after dark. - **Skies you can watch.** Clouds drift across Cloudline, stars twinkle in the Observatory, and flowers sway in the wind on the Commons. - **One pet each.** A dog, a cat, a rabbit, a tortoise, a snail, a budgie or a duck, and a name. The tortoise and the snail take their time. It is the only thing in the world you name yourself. The tile you put it on is its bed. It wanders near there during the day, walks home in the evening, and sleeps there at night, gently breathing, with its name above it. - **Doors.** Anyone can open or close any door. A door you cannot open would just be a wall. - **A spawn point.** Put it down and that is where you arrive when you come into the world. ### Your look Everybody looks like somebody of their own. Put a wardrobe in your home, walk up to it and press E, and choose: grown-up or kid, skin, hair and hair colour, a top, bottoms, shoes, glasses and a hat, each in lots of colours. You watch yourself walk round in it before you press "Wear it", and you can come back and change whenever you like. Anybody new starts as a character picked just for them. ### Picture frames Upload photos to your own photo library, then hang one in a frame. A frame against a wall hangs on the wall, and one out in the open stands on an easel. In the world the photo is shrunk to a dozen chunky pixels, and when you walk up and look at it you see the real picture. Anybody can look; only you can change what hangs in your frames. > **Builder's notes** > > - **Code.** The world is `deploy/site/world.js` (plain JS, a custom element > ``), hosted by `frontend/src/Books.gren`, with the server side > in `backend/src/World.gren` and the shared types in `shared/src/Api/World.gren`. > - **Data.** `world_floors` is keyed by `z` alone. `world_edits` is an > append-only per-person log holding each object's whole state, so the world > is the newest row per object. `world_heads` is how far along each person's > log a floor stands, which is what undo and redo walk. Building goes through > Postgres functions (`world_place()` and friends) so that a staircase's two > ends are one atomic statement. > - **Not in the log, on purpose:** door state (`shut`, where absent means > open), pet names, spawn points, and frame contents (`world_frames` → > `world_photos`). None of those is *building*, and putting them in the log > would drop them into somebody's undo history. > - **Look but do not touch** already holds on the server: every book write is > scoped to `user_id = caller`, and `world_frame_put` refuses anybody else's > frame or photo. > - **Land** is an even sector each, turned half a sector so the fences run > square. Ownership on a floor is read off the objects. This is a > four-person design; the island replaces it with family homes (Step 5). > - **Art.** `deploy/site/tiles.png`, `people.png` and `tiles.json` are the > real artwork. `tools/tileset/*.mjs` is only the recipe and writes to > `tools/tileset/out/`. See `tools/tileset/README.md` for how to add a > block, and the rules every sprite follows. > - **People** are drawn in the browser from a look by > `deploy/site/people-art.js`; see Step 4. > - **Undo** exists in the database but is not reachable from the page, and it > is unsafe to expose until it knows about staircases' far ends. > - Uploaded photos are served from `/uploads/` without a login. Their names > are 128 random bits, so they cannot be guessed, but anyone holding a link > can see the picture. ## The road to the island Eleven steps, roughly in order. The first four make today's world richer and let everybody look like themselves. Step 5 is the island and its family homes. Steps 6 to 9 are the things that make visiting each other fun. Invitations go out at Step 10, once there is plenty to do when you arrive. ## Step 1 · Picture frames **Status:** Done Photos from home, hanging in the world. This was the one island idea that also belonged in today's world, so it went first. - [x] A photo library: upload, shrink in the browser, store - [x] Hang a photo in a frame, take it out, swap it - [x] Hanging on walls, standing on easels - [x] A pixelated photo in the world, the full photo up close - [ ] Frames in more than one style (gold, painted, one for each set) - [ ] Bigger frames that span two tiles, for a family portrait ## Step 2 · A fuller toy box **Status:** Building now More things to build with. Homes are about to be the heart of the game, and a home is only as good as what you can put in it. This step never really ends, but the big push is done: five new sets, from three to eight, with over two hundred things to build between them. Set names were made up as the sets were drawn, and can change. **Around the house** (the Parlour) - [x] Fireplace, bed, comfy chair, bean bag, stool, floor lamp, bookshelf, fish tank - [x] Picture frame - [x] Wardrobe and chest of drawers, and a standing mirror - [x] Wall clock that shows the game time - [x] Potted plants: a fern, a cactus, a tall one for a corner, and vases - [x] Curtains for the windows, open and shut, like doors - [x] Rugs in more shapes: round, a long runner for halls - [x] Wall shelves and hooks, and a coat stand - [x] Toy box, rocking horse, a pile of blocks - [x] Piano - [x] A candlestick and a lamp table, lit at night - [x] A velvet sofa, a gramophone, floor cushions - [ ] The piano plays a note when you press E - [ ] Frames in more styles, to go with each set **Kitchen and bathroom** (Kitchen and Bath) - [x] Kitchen table, sink, refrigerator - [x] A range with a kettle on, and counters that join like walls, with a sink in one - [x] Kitchen chairs, a dresser of plates, a larder cupboard - [x] Clawfoot bath, a basin with a mirror, a towel rail, and a loo - [x] A washing machine, a highchair, a cake - [ ] Kitchen chairs that tuck under the table **A library** - [x] Panelled walls, arched windows, an oak door - [x] Tall shelves, a ladder, a card catalogue, piles of books - [x] A writing desk with a green lamp, wingback chairs, a window seat - [x] A grandfather clock that keeps the world's time - [x] A globe, a chess table, a typewriter, a sleepy owl **Outside the door** (the Front Yard) - [x] Mailbox, bird house, flower box, firewood, wellies - [x] Doormat, a porch light, and a house number - [x] A white picket fence and gate, which meets the orchard fence - [x] Washing line, a swing, a hammock - [x] Well, wheelbarrow, watering can - [x] Gnomes, sunflowers, roses, a bird bath, a rose arch, a sandpit, a bicycle **Island things** (Seaside) - [x] Sand, wet sand, shallow water to wade through, and deep water you cannot cross - [x] Palm tree, rocks, driftwood, shells, starfish, tide pools, a crab - [x] A boardwalk, dock posts and a rowing boat - [x] A lighthouse for the far point - [x] A striped beach hut, a deckchair, an umbrella, a sandcastle - [ ] A window for the beach hut > **Builder's notes** > > - A new block is a drawing plus one `CATALOG` entry in `world.js`. The flags > `light`, `lift`, `tint`, `magic`, `door`, `wanders` and `frame` cover most > things. Two were added for this step: `keepsSolid` (curtains are a door > that never lets you through) and `clock` (the world draws hands on a face). > See the tileset README. > - The five new sets are `parlour.mjs`, `kitchenbath.mjs`, `library.mjs`, > `frontyard.mjs` and `seaside.mjs` in `tools/tileset/`. The live art was > still byte-for-byte what the generator drew, so it was regenerated and > copied whole. Check `md5sum` again before doing that next time. > - `tools/tileset/preview-set.mjs` draws one set onto a preview sheet. > - Deep water stops you; shallows you can wade through. It is the one floor > marked `solid`, and a boardwalk laid over it is walkable, since a tile > has one floor. ## Step 3 · Guestbook **Status:** Next up A book that sits in your home (or today, on your own land). Anyone who walks up to it can press E and write a line: their name and the day are added for them. The owners can read every entry and tear out a page they do not want. It works in today's tower and moves to the island unchanged, so it is the best next step after the toy box. - [ ] A guestbook block, one per home (one per person in today's tower) - [ ] Write an entry: a line or two, signed and dated automatically - [ ] Read the book: newest first, page by page - [ ] The owners can remove an entry - [ ] A little "new" marker on the book when somebody has signed it since you last looked > **Builder's notes** > > - Like frames and doors, entries are not building, so they are not in > `world_edits`. A `world_guestbook` table keyed by the book's object id, > with author, text and time. > - Signing is one of the deliberate exceptions to look-but-do-not-touch: > anybody can add an entry, only the book's owners can remove one. > - On the island the book belongs to the family's home, so any member of the > family can tidy it. ## Step 4 · Make it yours **Status:** Done Everybody starts as somebody: the four of us as the characters we always had, and anybody new as a character picked just for them. To change, put a **wardrobe** in your home (it is in the Parlour's bedroom things), walk up to it and press E. Choose how you look, watch yourself walk round in it, and press "Wear it". Come back and change whenever you like. - [x] A wardrobe that opens a character maker, your own wardrobe only - [x] Grown-up or kid, eight skin tones, twelve hair styles and fifteen hair colours - [x] Eight tops, five bottoms, shoes, glasses and six hats, each in lots of colours - [x] See your character walk all four ways before you wear it, and a "Surprise me" button - [x] Change it again whenever you like; everybody sees it within the minute - [x] The four of us keep the characters we have, and can remake them too - [x] Anybody new starts with a random look of their own, the same on every screen - [ ] A mirror that shows you yourself, big, when you walk up to it > **Builder's notes** > > - People are drawn in the browser from a look by `deploy/site/people-art.js`, > which is also what the tileset generator uses to draw `people.png` > (`tools/tileset/people.mjs` re-exports it). The four originals are > presets in it, drawn by the same code as before: `people.png` came out > byte-for-byte the same. > - Looks are saved in `world_looks` (one row per person, the look as small > JSON text) through `GET /api/world/looks` and `POST /api/world/look`. > Nobody with no row has chosen; the page decides their look. The page > reads every saved look through `normalize()`, so an odd or old value > draws as the nearest thing it knows, and new options need no migration. > - Your wardrobe only: visitors see a wardrobe, and cannot open it. ## Step 5 · The island and its family homes **Status:** Planned The big one. A central island where every home stands on the shore around a shared middle, the way the plaza sits in the middle of today's floors. **Homes belong to families.** Everybody belongs to a family, and each family shares one home. Everybody in a family can build inside it and arrange it together. A home's front door **takes you inside**: the inside is its own space, as big as the family wants to build it, separate from the island outside. **Visitors look but do not touch.** It works the way today's world does: you can walk into anybody's home, look at their pictures and open their bookcases, but only that family can change anything. Signing the guestbook is the one thing a visitor can add. Watering somebody's plants comes later, with the garden. - [ ] Families: everybody belongs to one, and each family has one home - [ ] The island: a map with a shared middle and homes around the edge - [ ] A front door that ports you inside, and back out to the doorstep - [ ] Inside a home: floors to build on, shared by the whole family - [ ] Visitors can look at everything and change nothing - [ ] Homes nobody has moved into yet look empty: boarded windows, a For Sale sign - [ ] Bring your bookcases home **What comes along from today's world:** picture frames, pets, doors, every block, day and night, your bookcases and your books. The tower of nine floors stays where it is; the island is a fresh start. > **Builder's notes** > > - **Its own site.** Family Island is a separate deployment on its own > subdomain (something like `family-island.twinsparks.com`, name not > final), on the same server but with its own database and its own > accounts. You arrive straight at the game, or a start screen in front of > it. Nothing is shared with any other app: not the database, not the > login, not the address. > - **Books** may be copied across once, for the four of us, when the island > opens. After that the two are unrelated. > - **Families.** `families` (id, name), and each user has a `family_id`. > Ownership of everything built inside a home is the family's, not the > person's, so the permission check becomes "is the caller in the family > that owns this home". Pets, spawn points and photo libraries stay > per person. > - A home's interior could simply be a set of floors with an owner. Today a > floor is a `z`. Homes need a key like `(home, z)`, so "one floor up" is > still arithmetic within a home. > - A door that ports is a new door kind whose interact goes to another space. > The stair travel code already moves you between floors and fades through > black. Teleporting through a door is the same move to a different space. > - Undo is a per-person log today. Inside a shared home, decide whether undo > is per person (undo only your own edits) or per home. > - **Open:** is the number of homes fixed by the families set up ahead of > time, and does a family pick its plot on the shore or is it assigned? > - **Open:** how the code is shared between today's world and the island > (a copy that goes its own way, or something tidier). ## Step 6 · Mailbox and the courier **Status:** Sketch Letters, delivered the slow way. Write a letter at your mailbox and the **courier** picks it up. The courier walks a fixed loop around the island, quite quickly, and is fun to watch. But they only carry **one page of each letter per trip**, so a long letter takes days to arrive. You read page one with a note that more is coming. - [ ] Write a letter at your mailbox, to one person, one family, or everyone - [ ] The courier: a character who walks the loop around the island - [ ] One page per trip; the next page comes next lap - [ ] The flag goes up on the mailbox when there is mail - [ ] Some funny way to hurry the courier along (a bicycle? a pet who helps?) - [ ] Homes nobody has moved into: the courier just walks past them > **Builder's notes** > > - The courier's position can be worked out from the clock, the same way pets > are, with no ticking and nothing stored. Everyone sees the courier in the > same place. > - Delivery is a question of when the courier last passed your home, so it > too can be worked out from the clock plus when the letter was sent. > - One mailbox per home. A letter to a person still lands in their family's > mailbox, but only they can open it. > - The mailbox block already exists (Cozy Cottage, outside the door). ## Step 7 · The front-yard garden **Status:** Sketch Every home has a front yard with a garden in it. Plants grow over **real** days, not game hours, and anyone can water anybody's plants. Walking past a cousin's home and giving their tomatoes a drink is the whole idea. The yard is for growing things, not for decorating like the inside of a home. - [ ] Plant a seed in your yard - [ ] Plants grow through stages over real days - [ ] Anyone can water any plant; a thirsty plant looks thirsty - [ ] Show who watered it last ## Step 8 · Cobwebs and dust **Status:** Sketch If nobody from a family has been by in a while, cobwebs and dust slowly build up on the outside of their home, so everyone can see who has been away. Cleaning them is easy: anybody in the family just walks round with a broom. - [ ] Webs and dust appear the longer a home goes unvisited by its family - [ ] Anybody in the family sweeps them away in a few seconds - [ ] It never gets *too* spooky ## Step 9 · The family quilt **Status:** Sketch A shared canvas. A quilt is made of 9 or 12 blocks, and anyone can claim a block and design it. It is fine if there are fewer blocks than people. When every block is finished, somebody takes the quilt home and hangs it on their wall, and a new one is started. - [ ] Start a quilt and claim a block - [ ] Draw your block in chunky pixels - [ ] When it is finished, someone takes it home to hang ## Step 10 · Send out invitations **Status:** Planned The island opens its doors. Everybody gets an account made ahead of time, and the invitation is an ordinary family email. Joining is up to each person. **How signing in works.** Everybody has a username of their own. When you decide to join, you type your username and ask for a sign-in link, and the island emails one **to the address already on your account**. The link works once and only for a short while. It signs you in and asks you to choose a password. Nobody ever has a password they did not choose, so there is nothing to guess. Kids do not need an email address of their own. A child's account can use a parent's address, so the link goes to the parent's inbox. - [ ] Accounts made ahead of time: a username, an email address, and a family - [ ] "Email me a sign-in link", by username, to the address on the account - [ ] First sign-in sets your own password; after that you sign in with your username and password - [ ] The same link doubles as "I forgot my password" - [ ] The invitation email goes out > **Builder's notes** > > - **Usernames are unique; email addresses are not.** Several children can > share a parent's address, which is why the link is requested by username > and sent to that account's address. > - **Sign-in links.** Store only a hash of the token, with an expiry (an hour > or so) and a used-at time, and burn it on first use. The request form > answers the same thing ("if that username exists, a link is on its way to > the address we have for it") whether or not it does, and is rate limited, > so it cannot be used to find out who has an account. A new account has no > password at all until its first sign-in. > - **Sending email** goes through Gmail's SMTP with an app password. About > thirty addresses, so Gmail's sending limits are nowhere near, and mail from > Gmail is not treated as spam. The app password lives only in the server's > environment, never in the repository. > - Accounts and families are made by a small script run on the server, from a > list. There is no admin page on the island. ## Step 11 · Message in a bottle **Status:** Someday Throw a message into the sea and it washes up on somebody's beach. We liked this idea and have not worked out the details. ## Still thinking about - **Pet trips.** Your pet goes off somewhere and comes back. It needs a purpose. Maybe a pet can hurry up the courier. - **Group builds.** Something the whole family builds together on the shared middle of the island. ## Not for now Ideas we talked about and set aside, so they do not get suggested again by accident: **baking**, **a time capsule**, **seasons** (homes are decorated by their families, so seasons are up to them), and **a weekly visitor**.