Plans for Bedrock

This week I’ve been thinking about all of the work that still needs to be done for Bedrock as a project.

Bedrock

There’s a lot of work that still needs to be done before this project can stand on its own. It’s one thing to write a specification, a manual, and a couple of implementations, but there’s so much more peripheral work that needs to be done to support the project from other angles. Things like more documentation, tutorials, example programs, developer tooling, and a community hub.

Specifications

I’ve already written a full specification for the core, assembler, metadata format, and ten of the twelve device interfaces. It’s a dense document, because it’s written to rely as little as possible on existing knowledge and to be as difficult as possible to misinterpret. I still need to design and specify the tone and sampler devices (used for playing audio from generated tones or recorded samples), but that’s probably at the bottom of the priorities list.

I’ve recently been working on a one-page spec for Bedrock, a specification where the entire core system fits onto a single sheet of A4 paper. The motivation behind this is to have a distilled spec in a tiny package that can be printed, folded, and stored alongside hard copies of Bedrock programs for the long term. I’m picturing programs printed as source code or hex values and stored in a small folder, so that someone can implement an assembler and an emulator from just that one sheet, in order to run the programs again in a couple of decades time.

Some compromises have to be made in order to condense the spec to so small a package. Instead of using precise, verbose language, I’m having to lean more on the common-sense of the reader, on the reader already being familiar with some computer terms (shifting, rotating), and I’m also leaving out some more nit-picky details (maximum addresses and lengths, implementation defined stuff).

I’m also leaving out the device interfaces, or at least not including them on the first A4 page. They can each get their own half page, perhaps. Despite the simplicity of the core system and assembler, the device interfaces have to interact with the real world, and are just a huge pain to specify. The first four devices are fine, they expose very tidy, abstract capabilities (system info, memory, math, date and time). But look at the input device: it has to work seamlessly with not only keyboards and mice, but also touchscreens, graphics tablets, on-screen keyboards, and various game controllers. And worse is the filesystem device, where every file system has a completely different set of constraints (case sensitivity, character encodings, path separators, path lengths). A specification needs to be able to package up all of these messy details into a small, friendly interface.

The plan is to have the following specification documents:

• Full specification
  This is the full, unabridged, normative specification that describes the entire system in exacting detail, the kind of thing you could store in a vault for a hundred years.
• One-page specification
  This is a short, abridged specification for educational purposes or for when the full specification is just too long. It isn’t normative, the full specification is the only ‘correct’ one.
• Implementation handbook
  A supplementary guide for people who are implementing Bedrock on another system. Where the specification contains all of the MUSTs, this book will contain all of the SHOULDs, things like auto-hiding the system cursor or handling hidden files.
• Style guide
  A style guide for Bedrock assembler, to help with writing tidy code in a consistent style.

User manual

The role of a manual is to teach the user how to use the system, while protecting them from ever having to read the specification. I wrote a user manual a while ago, but it’s pretty average, it’s too similar to the specification. I need to rewrite the whole thing from scratch, and to split it into multiple different documents, each one targeting a different audience.

The plan is to have the following user documents:

• User manual
  A clean and tight explanation of the entire system, in a form not dissimilar to the PICO-8 user manual. I’m not 100% sure what this looks like yet, whether it contains examples or explanations. I’m inspired by the user manual for AT-Robots, a battle-bot programming game for DOS. The tone is that of a friend helping you to learn the system.
• Reference handbook
  A small and dense summary of the entire system, for people who already know the system but who can’t remember the order of values for an instruction or the port number for a device function. Packed with the kinds of tables that you can hang on your wall or keep next to your keyboard.
• Tutorial for absolute beginners
  Aimed at people who haven’t ever written a program before. Prior art would be the compudanzas uxn tutorial or the Usborne books. I’m picturing something written for kids, as much as possible.
• Introduction to Bedrock
  A quick overview of the system, for people who are interested in the system and maybe know a bit about programming. This would be more of an evangelism piece, convincing people that Bedrock is something worth looking into.
• Example programs
  A series of well-annotated exemplar programs, to demonstrate what a good program looks like. These would be useful for people to play around with in a live programming environment, poking different parts of a program to see what they do.
• Topic guides
  A series of books on different programming topics in Bedrock, things like array handling, string handling, image handling, dynamic modules.

Developer tooling

Currently, to write and run a Bedrock program you have to use the command line, which is a big impediment for non-programmers. Debugging is even harder, I can’t really expect people to be enthusiastic about having to read through stack dumps to debug their programs, simulating the system in their heads. No, there’s vast room for improvement here.

I’ve had plans for a while now for a program called Bedrock GRID (graphical interactive debugger), which will be an all-in-one program editor and debugger for Bedrock. Program memory can be visualised as a grid of coloured cells, with the colours representing byte values or a heat map (hot loops will be red-hot, dead code will be cold), live-updating as the program runs. Here are some other feature ideas:

• Attach watchers to memory addresses and show a graph of the value over time, or pause the program on change.
• Hover over a piece of code and the corresponding program bytes will light up on the grid, and vice versa.
• Track the provenance of stack values, for finding the piece of code that pushed each value
• Scrub a value in the code (dragging to increase or decrease the value) and the program re-runs live to show what changes.
• Assemble a program as a native executable for Windows, Linux, Mac, Nintendo DS, as an HTML file, or for any other supported platform.
• Pop-up documentation for instructions and annotated functions. Quickly see a macro definition when hovering a macro reference, or the corresponding label definition when hovering a label reference.

Another facet of tooling is making Bedrock programs for creating the assets that are used to make programs. A sprite editor, a font editor, a music editor. A native assembler and text editor that runs inside Bedrock, so that program development is self-hosted.

And on the other side of tooling is the languages used to write the programs. I’ve always planned to have three officially supported languages for Bedrock: Bedrock assembler, Torque, and Peak. The first two are complete, the third is a long way off.

Platform support

Bedrock is no use without the ability to run programs on different platforms. This is probably the most painful task, despite the advertised ease of implementing Bedrock, because the list of platforms is endless and the effort to develop for each one is so high. It isn’t that Bedrock is hard to implement, it’s that I have to learn a whole new development system and probably programming language each time. So far, I’ve implemented at minimum the core system in:

• C (for Nintendo DS)
• C++
• Turbo Pascal (for DOS)
• Web Assembly Text (for web)
• Python
• Rust (for Windows, Linux)
• Torque, PIC machine code (for bedrock-micro)

It’s not so bad implementing the core, but it takes so long to figure out how each platform handles graphics, or mouse and keyboard input, or filesystem access, and how to wrangle it all into a happy event loop.

I know it’s going to be a massive pain to support Android, iPhone, and macOS in the future. Android because I’ve developed for Android before and it was not easy, and iPhone and MacOS because I don’t own any Apple hardware and don’t really want to fork out for the developer license cost or whatever it is.

I’ve still also got to implement forking in bedrock-pc, as well as the clipboard and registry devices and a few other niceties like taking screenshots and screen recordings with the emulator.

In addition to the software implementations, I’m really keen to create at least one hardware implementation, as proof that the system can run well on bare-bones hardware. This will be bedrock-micro, running on a microcontroller and a dream.

Programs

If there’s one thing that will make people believe in Bedrock as a project, it will be having a large library of useful programs, running in the browser or on any other platform. The proof of the pudding is in the eating, as they say. Here’s some screenshots of the kinds of programs available for Uxn:

I’m off to a decent start on that front with Cobalt, which was always intended to be a sort of stress-test for Bedrock, seeing how far I could push a program on weaker hardware. But I’d like to build up a solid library of useful tools and interesting games.

Community hub

There needs to be a clear place for people to go if they need help, or to share what they’ve made, or to collaborate with one another. The plan for this is the Bedrock Public Library, which I’ve talked about in earlier debriefs.

The BPL is inspired by the PICO-8 BBS, a sort of combination forum and program repository. It’ll be a website, built on top of an HTTP API that’ll make it possible to integrate the system into other programs, so that people could, say, publish programs or browse libraries from directly inside GRID (mentioned above).

Ambition

I have a lot of ambition with where I want Bedrock to be in 10 years. I want Bedrock:

• to be a good introduction to programming for kids, the kind of thing that could be taught in an after-school program for kids or teenagers.
• to be a viable system to use for participating in game jams, with Peak as a fast language to program in, with the BPL providing useful libraries to build on, and with assets created with other Bedrock programs.
• to be a decent approach for cross-platform software development, where I can write a game using Bedrock and release it for phones, computers, consoles (handheld and television), and the web, no additional effort required.
• to be able to run serious software, like text editors, spreadsheets, diagramming tools, novel sequencers, and high-quality games.

I have a lot of work to do.

Thanks

Whoops, that took a while to write, I need to get back to my studying. Thanks for being interested in what I do and supporting my work. I’ll slowly chip away on these plans and we’ll see how they turn out.