Level author

Download the game, open the level list and play any level. To build your own, create a level in the editor and put a 1-2 minute track into its folder

Game bugs go to the releases issues, questions go to Discord. Attach the version string from the settings and the steps after which the bug appears

Before you play, the game shows how heavy a level is to run on your device, as a gauge of five bars: the more bars are lit, the lighter the level. Green bars mean it runs smoothly, yellow means it is

The editor is built into the game, there is nothing extra to install. A level in it is a folder with a track and files, which you take from empty to ready to publish

A level is a folder of files, the first one takes six steps to build, and the whole editor rests on six ideas: object, frame, span, layer, parent, key

A level is an ordinary folder on disk: the level file, the metadata and everything it uses. Build it in Json and hand it over as a copy of the folder, nothing needs installing

Six steps to the first playtest: create a level, add a track, map the rhythm, place objects, run a playtest, save

Object, frame, span, layer, parent, key - the six ideas the whole editor rests on

A level counts time in its own frames, not in screen frames, so it plays the same on any hardware. You set the level's length, and the fps is best left at the default, 60

A key is a value on one frame of one track, plus the easing it is reached with. Everything in a level that moves, changes colour or switches on and off is a list of keys

The minimum level is one track. Images and fonts you bring yourself, and all of it lives in the level folder

The minimum is a track. Everything else is optional, and nearly all of it you bring yourself

Convert the track to ogg: it weighs 8-10 times less than wav and, unlike mp3, adds no silence to the start of the file. Apart from ogg, only mp3 and wav load

If a shape will do, use a shape: it has no file, no memory cost and no rights question. Make an image the size of its place on screen, no more than 2048 for a mobile level and 4096 overall

A level lives in its own folder in levels inside the game's folder. Do not rename the files it uses, and a full backup is a copy of the level folder

A level you publish may only hold files with an open licence no stricter than CC BY-NC or with the author's permission. A level for yourself can be built from anything

A track can be used if its open licence is no stricter than CC BY-NC or its author directly allowed it in the level. A track from YouTube, SoundCloud or Spotify needs its author's permission

A resource qualifies if it has a suitable licence or the rights holder's permission. There is no third way

Safe by default: music from ccMixter, Freesound and Kenney, images from Poly Haven, Pexels and Unsplash, fonts from Google Fonts. Nothing may be taken from YouTube, SoundCloud or Spotify

The record notes where a resource comes from and on what terms: the link, the licence, permissions, authors. An empty licence field means "nobody checked", and such a resource is refused

Every service checks a level by its own rules, so one can accept it and another refuse it. Only an error blocks publishing, a warning sends the level to moderation

Write to the author with the template, keep points 1-3 intact and save the reply. Only a permission that directly allows the level to be distributed counts, not one for personal use alone

A good level is one where the player understands what killed them, moves with the music and wants to try again

The player has to understand what killed them. Show a danger before it becomes dangerous, give at least 12 frames to react and make danger stand out more than decoration

Map the beat grid first: the tempo, then the offset, then the beats per bar. Put the level's peak on the track's peak, and give the player a breather in the breaks

Design against the player's own numbers - every one of them is on 6_avatar and 7_damage - and a human reaction of 12-15 frames. Show a new pattern in a safe form first

Keep meaningful content off the edge: other screens put the edge elsewhere, and a phone cutout can cover a projectile. Camera shake is good for one bar, fast spin and sharp zoom make people sick

Route content colour through a theme reference, keep literal colours for what is truly unique. Turn post-processing on at a peak and off again, or projectiles lose their edges

A theme is a palette of 64 colours that objects refer to by slot number. Change the theme, and everything that refers to it changes with it

Build a picture from built-in shapes first and draw your own only where none fits. Lay light and shade over one base shape, make every repeated element a prefab, and check the result against the origi

Habits, not design: in what order to build a level, how not to do work twice and not lose it, how to check it with the bot, hand it over and build it with an AI assistant. Start with the order of work

First the track, the fps, the beat map and the markers, then a skeleton of plain shapes and its playtest. Decoration, the theme and effects come last

Objects you will later have to change all at once make a prefab, however many there are. Content that can be described by a rule makes a generator. In every other case just copy

The command palette (Ctrl+Shift+P), content search (Ctrl+F), the Ping button and the arrow keys on a timeline save the most time. Any key can be rebound in the settings

Your work is protected by autosave, undo and a copy of the level folder. Only a copy of the folder is a complete snapshot of the level. Changing the file format and deleting a level cannot be undone

A bot plays the level with the same controls you have and checks readability, not difficulty. It does not guarantee the level gets cleared

Pack the level folder into zip or tar.gz, and encrypt it with gpg for a password. On another machine the unpacked level plays right away, and the game reads such archives itself

An AI client that speaks MCP can edit the level open in the editor while you watch. Each AI batch is one undo step, and the AI cannot publish, delete files or write over another level

Whether a level runs on players' devices is decided by the number of shapes in a frame and by overdraw. Start with the level budget, and if you make a level for phones, read about mobile devices too

A phone comfortably holds about 1000 shapes in one frame, a weak PC 5000-10000. Overdraw costs more than the count: translucent things over the whole screen, layer upon layer

On a phone a finger covers the screen, and the system takes the edges. Keep what matters away from the edges and test the level on a weak phone: full-screen translucency drains it first

What a given field or button of the editor does, one page per panel, window or tab. The reference is not read through: you come here from a search or a link in an article

The project's main list of terms. The game's interface, these docs and every other text about Bullet Hero use these words, and a new term is added here first

Metadata is the level's cover: name, description, picture, authors, age rating, difficulty and content warnings. Today a level reaches another person as a folder or through Steam Workshop

Timelines show the level over time: objects, the selected object's keyframes, a prefab's template, audio and events. The beat grid helps you place all of it on the music

The hierarchy is a tree of the current frame's objects by parent. Every timeline has its own clipboard buffer, and the command palette finds any editor action by name

The object inspector edits the selected object's fields, the keyframe inspector edits the selected keyframes, on every track the selection touches at once

An effect is VFX Graph particles whose parameters are split into modules: how many particles, where they fly out from, how they move, what colour and size they are. You edit them in the inspector or i

An audio track's sound goes through a chain of effects: there are 11 of them, from normalize and compressor to echo and reverb. The chain, speed and volume are set in the audio track inspector

A generator creates content and applies it to the level in one operation that can be undone in one step. Every generator is run from the "Generators" window on the toolbar

A modifier changes what is already in the level: it removes content, recalculates fps, flattens prefabs, quantizes keyframes, fits and shifts spans. A run is undone in one step

Everything that belongs to the level itself is set here: length, fps, seed, orientation, metadata, publication. This is also where the level is launched, checked against the rules and restored from a

A level's textures, shapes, themes, effects and prefabs live in its folder and travel with it. Each resource has its own card with its source, licence and authors

In Prefab Mode you edit the template, and saving carries the edit to every placement of it. Enter with the "Edit Prefab" button in a placement's inspector, go back to the level with Ctrl+Shift+E

Export saves the level outside the game as a folder or an archive, together with every file it uses. A password encrypts the level's content on disk, and a forgotten password cannot be recovered

Autosave, the grid, selection, gizmos and new-level presets are set here. Autosave is on by default and fires 60 seconds after an edit

The hierarchy, inspectors and timelines are docked around the viewport. A click on the handle at a panel's edge opens or closes it, a drag changes its width

Collections hold the resources you reuse across levels. A level never refers to a collection: importing copies the resource inside, and the level plays anywhere

A level is sent only from the "Publication" tab in the level settings: as an archive or to Steam Workshop. The report checks the level by itself, and errors in it block sending

The editor renders the open level into a video file through ffmpeg installed on your computer. Rendering is offline, one frame at a time, so the video is exact however slow the machine is

The SDK is the Bullet Hero level format as an open C# library. The game reads and writes levels through it, and your program can do the same

The SDK is the BulletHero.SDK package on nuget.org, or a build from source. Unity takes it as a git submodule, and the ConsoleSmoke sample checks that your levels read

A level is a folder: content in level.json or level.blob, metadata in metadata.json or metadata.blob, a cover and media files. Backups, records and player settings stay on the device

A level is exported as a folder, tar.gz or zip, optionally under a password: zip with AES-256 or OpenPGP. The SDK detects the format of a received file by its first bytes, not by its name

There are three versions: gv for the game, sv for the SDK, mg for the generation of the model format. By mg the SDK migrates an old file and refuses to read one with a generation newer than the build

You call validation yourself through ValidationFacade, it is not built into saving and loading. Findings are split into Error, Warning and Advice, and ValidateAndFix repairs what it can

A service describes which levels it accepts with a PublishProfile file: licenses, resource sources, required fields, size limits. Adding a service means writing a file, not editing the analyzer

Bullet Hero is a free hybrid of a rhythm game and bullet hell. No account is needed, and there is no server yet. Players make levels in the built-in editor and pass them on as a folder or an archive

I use AI, and I think it is worth using. But properly: as a tool whose work I check, not as something that thinks for me. Used without thought, it produces a lot of text and code that looks right and

Bullet Hero is free, runs on Windows and Android, and its SDK, docs and builds are open. The core holds thousands of objects on screen on phones and is covered by more than 8000 tests

Questions, feedback and your levels go to Discord. Anyone can help the game: fix a mistake in the docs, add a translation, report a bug or make a level

Talk and questions go to Discord, videos to YouTube, game bugs to the issues of the bullet-hero/releases repository. The source code is in the bullet-hero organization on GitHub