Oscean and a static wiki engine that fits in 64kb of memory

What Oscean is, and what a Uxn wiki means

Oscean is described as a static site written in Uxntal, a stack-machine assembly language designed for a portable virtual machine. The repository is the source for the Oscean wiki, and the homepage is wiki.xxiivv.com, where the on-site documentation lives.

The most consequential sentence in the README is about memory. The database tables are stored as plain-text files designed to fit in Uxn's 64kb of memory. That single constraint determines everything about the design, so it is worth being precise about what it means.

Uxntal programs run on Uxn, a portable virtual machine with a 64kb address space, roughly the size of a 1970s home computer. A conventional wiki engine cannot run in that space, and neither can a conventional static site generator. What can fit is a program that reads small plain-text tables, builds an index in memory, and writes out static HTML pages. Oscean is that program.

That is the whole point of the project and also its limit. The audience is not a team that wants a documentation platform; it is a person, or a small group, who wants a wiki with the same shape as the ones from the home computer era: text pages, links between pages, and an index you can move through. The topic list says as much, with assembly, uxn, exocortex, memex and wiki.

The primary language is listed as HTML, which reflects the output rather than the input: the engine is written in assembly, and what it produces is a set of HTML files.

The main branch is the live version, so the default branch of the repository is the deployed site rather than a staging area. That is a deliberate choice for a project where the site and the engine live in the same tree.

Assembling the engine into a ROM

The build is one command, and it is the clearest statement of the project's nature.

The oscean.rom file can be assembled with drifblim, and the actual assembly step is:

uxnasm src/oscean.tal bin/oscean.rom # build wiki engine

Uxntal source goes in, a ROM comes out. There is no package manager, no dependency resolution, no transpiler and no framework. The source lives in src/ as a .tal file, and the artefact lands in bin/.

Running it is the same story. The rom does not have a graphical interface, but can be used with the uxncli emulator, and the command is:

uxncli bin/oscean.rom

So the tool is a ROM run under a virtual machine, which is a very different interaction model from running a generator binary. There is no command line of your own to learn, no flags to discover, and no output directory argument. The behaviour is whatever the ROM does when the machine starts it, and the deployment target is a directory of static files.

The presence of a makefile at the repository root, alongside the site/, etc/, links/, media/ and docs/ directories, is the one piece of the build system the README does not describe. The makefile is the natural place for the multi-step sequence of assembling the ROM, running the pre-processor and copying the static assets into the output, but the README does not document its targets, so anyone building from source will need to read it.

The repository also has a CNAME file, which is the GitHub Pages custom domain configuration for wiki.xxiivv.com, and a 404.html at the root. Those two files, plus the site/ directory, tell you the deployment target is GitHub Pages rather than a bespoke server.

The pre-processor: entry-log and entry-map

Before the engine runs, a pre-processor step generates the temporary files the wiki engine uses to populate the wiki. The README names two of them and describes what each contains.

The first is entry-log, which contains all the diary logs for that entry. The second is entry-map, which contains all the incoming links for that entry.

These two files are the entire data model of a link-driven wiki, and understanding them tells you what the engine can do. An entry has outgoing links because it is a page. It has incoming links because other pages point at it, and that set is what makes a wiki navigable in both directions and what makes a backlink view possible. And it has a log, a dated diary of activity attached to the entry, which is the mechanism behind any chronological view.

So the engine's job is to read the content, resolve the links between entries, and emit static pages that carry the resulting graph. The link resolution is a two-pass operation: find what each page points at, and find what points at each page. Both passes are pre-computed into entry-map, and the engine consumes that rather than re-parsing everything at render time, which is exactly the kind of trade that 64kb forces.

The consequence is that the pre-computed files have to be regenerated whenever content changes, and the generation step is separate from the assembly step. That is why the build is not a single command in practice, and why a makefile is the sensible way to drive it.

The design also has a pleasant property: because the tables are plain text, a wiki maintained in Oscean is greppable and diffable like any other text project, and a page is a file you can read with any tool.

The hosting story: static output, a real home page

Oscean is a static site, and the repository tree shows what that means in practice.

There is a site/ directory that presumably holds the source pages, an etc/ directory, a links/ directory, a media/ directory, a docs/ directory, and an index.html at the root along with the 404.html and the CNAME. The docs/ directory is where the on-site documentation lives, including the about page the README points to, and the media/ directory holds the assets referenced by the pages, including the crest logo the README embeds.

Because the output is static, hosting is a solved problem rather than a project. The CNAME file binds the repository to wiki.xxiivv.com through GitHub Pages, and a static wiki of this kind can equally live on any static host or object store. There is no server process, no database to back up, no runtime to patch. The cost moves to the build step: you commit a change, the site regenerates, and the previous state is whatever is in git history.

For a wiki that is mostly a personal knowledge base or a small project documentation set, that is an attractive profile. Every version is in version control, every page is a text file, and the published site cannot break because of a runtime error at request time, because there is no request time.

The same property sets a limit, though. A static site has no dynamic features, which means no server-side search across the whole corpus, no accounts, no comments and no live updates. Whatever interaction the wiki offers has to be resolved at build time or handled in the browser. And the entries, being plain text tables bounded by 64kb, are not the place for a large collection of documents.

Licensing, and the two regimes inside the repository

The Extras section is short and has one point in it, but the point matters.

The README says to see the LICENSE file for license rights and limitations, which are MIT, and that the media assets are BY-NC-SA 4.0. So the repository carries two licences, and they apply to different things.

The code, which is the Uxntal source, the makefile and the tooling, is MIT. That is the permissive licence with no real conditions beyond keeping the notice, and it means you can take the engine, modify it, and ship it.

The media assets, which are the images, the crest logo and the audio and artwork used on the pages, are Creative Commons Attribution-NonCommercial-ShareAlike 4.0. That is a different kind of grant. NonCommercial means you cannot use the assets for commercial purposes without a separate permission, and ShareAlike means a derived asset set has to carry the same terms. A project that reuses the engine code and the artwork is therefore subject to two regimes at once, and the artwork is the restrictive one.

The README also points at the About page on the wiki for the media terms, which is where the details of what exactly is covered live. The project is careful to separate code from content here, and that separation is also visible in the assets section of the readme, which credits miHoYo for game content and assets in the case of the wider family of projects the author maintains.

The licence is also the reason the project accepts pull requests. The README says pull requests are welcome, and it is a repository with no GitHub releases, so contributions come through the branch rather than through a release process.

Where Oscean is the wrong choice

Three boundaries are worth stating plainly.

The first is the 64kb constraint, and it is not a soft target. The tables are designed to fit in that space, which means the total amount of content in the wiki is bounded by a number from the era of small computers. That is fine for a personal wiki of a few hundred entries, and it is not fine for a documentation set with thousands of pages or with any large attachment. A wiki that outgrows its index needs a different engine, not a bigger one.

The second is the interaction model. A ROM run under uxncli with no graphical interface means the build is a black box from the command line: you do not pass it options, you do not get a usage message, and the README does not document what happens when it runs. For someone who wants to script the generation, for example to build a copy of the site in CI for a pull request, that is awkward. The readme says the main branch is the live version, which suggests the update path is commit and push rather than build and deploy.

The third is the audience. Uxntal is an assembly language for a specific virtual machine, and Oscean is written in it. A team that has to maintain a wiki generated by this engine needs someone who can read Uxntal, or at least someone who can follow the source when the pre-processor or the entry tables need changing. The pre-computed entry-log and entry-map files are the part most likely to need a fix when the content model changes, and they are the part with the least documentation in the README.

The honest way to read the project is as a demonstration and a personal tool: a static wiki engine whose whole design fits inside a home computer's memory, published as a working site, with the source available for anyone who wants to build a similar thing.

Editorial conclusion

Oscean is a good fit for a small personal or project wiki whose pages are text and links, because the output is static files you can host anywhere and the engine itself is a single ROM that runs in a fixed 64kb of memory. It is a poor fit for a wiki with binary attachments, a large article count, or a team that expects a normal editing interface, since the whole design assumes the content is small enough to index in 64kb and the target audience is someone comfortable with a Uxn virtual machine. Before adopting, read the on-site documentation rather than the repository readme, because the README itself points there for more up-to-date details, and check the media licensing separately, since the code is MIT while the media assets are BY-NC-SA 4.0.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. XXIIVV/oscean on GitHub