Pixel Knights

A small pixel island in your sidebar, with a castle, a village, and the units that hold them. It reads out your code. Errors land raiders on the shore, and fixing them lets the garrison cut them down. Warnings, uncommitted work, and your build and test tasks show up on the island too. The whole thing is one canvas in a webview. No accounts, no tracking, and nothing leaves your machine.

Features

• An island of stacked elevations, drawn from the Tiny Swords tileset. From the top: a monastery with its Monk, a row of hillside houses, an archery range, the castle, the barracks, and a village on the ground. Every elevation of the fort has a tower on its corner
• A garrison that lives where it is posted. Archers on the walls, Lancers guarding the monastery, Warriors at the barracks. No unit in armour starts on the shore, because the ground belongs to the Pawn
• Grass stairs cut into each cliff, on opposite sides, so the elevations zigzag. The units walk them. Soldiers come down from the upper elevations, garrison figures leave their posts to walk the village, and the Pawn carries wood up the stairs to repair the buildings
• Raids driven by your errors. One red raider per error, up to three. Every Archer on the island opens fire at once, and a Warrior and a Lancer come down the stairs to meet them
• More of your code on the island. Warnings are Red Pawn thieves who carry gold out of the village houses and pile it on the shore. Fix one, and the village Pawn throws a thief into the sea and takes the gold home. Uncommitted files bring out Pawns to haul work up to the castle, and a commit delivers it. Commits you have not pushed wait at the castle gate, and merge conflicts set the castle on fire. A running build task sets the Pawns hammering, a failing test task sets a roof on fire, and a passing one has the Monk heal the knight
• Your debugger too. A debug session brings the rubber duck into the shallows, and a breakpoint stops the knight in its guard
• The island remembers. It counts raiders slain, commits delivered and days on the island. The count stays on your machine, in VS Code's own storage, and shows in the status bar tooltip
• Day and night. The island grows darker in the evening by your local clock, and lighter again in the morning
• The island scrolls. It is about 1,100px tall, taller than most sidebars, so the pane shows part of it and scrolls. It opens on the shore, and if raiders land while you are scrolled up to the castle, it scrolls back down to them
• The layout is worked out from the width of the pane, so the scene rebuilds when you make the sidebar wider or narrower instead of getting cut off
• Four colours, blue, black, purple and yellow, changed live from settings. The units and every building change together
• A status bar entry opens the view, and Pixel Knights: Focus Companion View does the same from the command palette
• Pixel Knights: Stage a Practice Raid lands three raiders that fall one by one, so you can watch a raid without breaking your code. Pixel Knights: Copy Island Record copies the island's count to the clipboard

Install

Search Pixel Knights in the Extensions view, or:

code --install-extension nauqh.pixel-knights

How the island reacts

The extension sends the state of your code to the island. That is every error, with its file and line. It is also the number of warnings, uncommitted files, files in conflict and commits not pushed, whether a build task is running, whether the last test task failed, and whether a debug session is running or stopped. Everything below is the island's reading of that. It responds to whatever produces your diagnostics, such as a language server, a linter or a compile task, and not to any particular editor event.

The rest of your code shows up like this:

Tests here means a task in the Test group, such as npm test. Results shown in the Test Explorer are not visible to other extensions, so they do not reach the island. The git readouts need VS Code's built in git extension. Without it the village is simply never busy.

The record counts an error as a raider slain when it goes away, even when it went because its file was closed. It is kept in VS Code's global storage, so it is the same in every workspace, and it never leaves your machine. The practice raid is not counted.

Diagnostics are debounced by 300ms, and a state identical to the last one is dropped rather than posted, so a busy language server does not wake the render loop.

The garrison

Every soldier is posted at a building. It stands either on the deck on top of that building or on the ground in front of it. Archers go on top, because an Archer is only worth having where it can see. The rest stand at the gate.

The guard is deliberately small. A castle elevation is about 190px of ledge at a normal sidebar and the castle itself covers 156 of it, so a bigger guard fills the whole ledge and reads as a queue rather than as a garrison.

Each elevation has its stair at one end, and the two tiles of ground beside that stair reach one row further down than the rest. The tower stands on the front edge of that step, level with the top of the stair beside it. The two elevations above the fort are not walled, so a tree stands there instead. The stairs alternate sides, counted up from the barracks, whose stair is always on the right. That is the beach side, which keeps the knight's run down to a raid short. It also means the tower never competes with the castle for space, so every tower appears at every pane size.

The castle and the barracks do need room, so what else you get depends on the pane.

Greenery on the upper levels

Bushes, rocks and the two short trees are scattered on the elevations as well as on the ground, following what Pixel Frog does in the pack's own promo art, where scrub grows along the lip of every cliff.

Two rules decide where it goes, and both come from the size of the ledge:

1. It sits on the lip, not spread over the whole elevation. An elevation is three tiles of grass and its building stands taller than all three, so anything placed behind a building is not partly hidden, it is completely hidden.
2. If there is no room beside the building, it grows at the foot of the wall instead, at the building's outer corners, drawn over the base stonework. Never across the gate, and never where a guard is standing.

That second rule is what makes it work at sidebar width. The castle elevation is 160px of ledge at a 300px pane and the castle covers 156 of it, so there is nothing to plant beside. The gap does not reach the 56px a bush needs until the sidebar is about 420px wide.

The monastery and the hillside houses are the exception. Their buildings are short enough to leave the back of the elevation showing, so trees also grow along the back of those two, clear of the buildings, the way the pack's own banner crowds its hills.

Only Tree3 and Tree4 are used up here. Tree1 and Tree2 stand 120px, taller than the elevation they would be standing on. The trees up here are scenery and are never cut, so the woodland the Pawn works stays on the ground, a walk from his yard rather than a climb.

When nothing is wrong

Which is most of the time, so the island is built to be worth leaving open. Every elevation can be walked on, and the stairs are the only way between them.

None of it runs to a fixed script. Each unit picks its own jobs, and the long ones have a wait between them, so the island is quiet more often than it is busy. The moment a raid lands it all stops. Anything above the ground walks back down the stairs, anything indoors comes out, and the line forms.

Nothing is remembered between sessions yet. See plan.md.

The chronicle

The button at the top right of the view shows the pack's shield icon while the island is at peace and its sword once there are errors, with the pack's arrow pointing down, or up while the panel is open. It opens a panel with two parts. Live activity says what each unit is doing right now. The chronicle is a log of what has happened, written like the chat log of an old strategy game: a time, then who did what, with names and items in brackets.

Each line is written at the moment the thing happens, so a Pawn carrying wood for ten seconds is one line, not ten. The panel is framed in the pack's own SpecialPaper art and keeps the last 40 lines. If you scroll up to read older lines, new ones do not pull you back down.

A file and line in brackets is a link. Click it, or press Enter on it, to open the file at that line. It only opens files the extension has reported an error in.

The island

Tiny Swords is drawn at 1x on a 64px world grid, which is far too big for a sidebar, so the scene is not simply scaled down with CSS. Two rules keep the pixels straight:

1. Resize the art once, and only once. Each sheet is drawn one time into an offscreen canvas at half size, with smoothing off. Every draw after that reads from that cache at 1:1. When the pane is wide enough to be worth it, the whole viewport is scaled up by an integer factor, never a fraction.
2. Integer positions. No sprite ever lands on half a pixel, so nothing shimmers as it moves.

Units are not resized to a common body height. Each one stands on the ground contact point drawn into its own shadow, which is why the Lancer, whose frame is mostly spear, comes out the right size next to the Warrior. Draw order sorts on that same contact point, so whoever is further down the screen is drawn last.

The terrain is built from the pack's tilemap rather than from pre-cut images. It uses a nine slice for the water edge, another for each elevation, and a stone wall row that stands on grass. The stairs are the pack's diagonal grass ramp, two tiles tall, and each elevation's edge drops a row where the ramp meets it. Without that drop the ramp looks like a mound instead of a way down.

Configuration

Colour changes are sent to the open view straight away, with no reload.

Development

npm install
npm run build

Then press F5. That launches an Extension Development Host with Pixel Knights loaded. Open it from the activity bar or from the status bar. npm run package builds a .vsix you can install locally with code --install-extension. It bumps the patch version in package.json first, so to rebuild the same version run npx vsce package instead.

If you also have the Marketplace build installed, both use the same icon in the activity bar. The launch config passes --disable-extension=nauqh.pixel-knights so that only the workspace copy loads. It does not pass --disable-extensions, which would switch off the language servers too, and with no diagnostics there is nothing to raid you. The copy that does load says which one it is. The view header reads Pixel Knights [DEV] with the version next to it, and the status bar entry ends in [dev].

src/extension.ts     startup, diagnostics, git and task watchers, webview host
src/world.ts         what the host tells the island, shaped from plain data
src/sprites.ts       the asset list: every sheet, and where it lives
media/companion.js   the whole renderer: layout, tilemap, animation, sprites
media/tiny-swords/   the copy of the asset pack
docs/plan.md         where this is going

npm run watch rebuilds src/ on save. The renderer is plain browser JavaScript with no build step of its own, so editing media/companion.js only needs a reload of the Extension Development Host.

One thing has to match across the two sides. The sprite keys in COLOUR_FILES, SCENE_FILES and UI_FILES in src/sprites.ts build the list of URIs, and they must match the keys the renderer looks up in the SPR and NATIVE tables in media/companion.js. Adding a sprite means editing both files. One says where the art is, the other says how big it is and where it stands on the ground.

If the sprite comes from a part of the pack that is currently excluded, you also have to relax .vscodeignore, which keeps the unused teams out of the .vsix.

Credits

All artwork is from the Tiny Swords pack by Pixel Frog, used under its license terms. The code is MIT, the artwork is not. See LICENSE and THIRD_PARTY_NOTICES.md. Purchase the pack from Pixel Frog.