Starbreaker is a playable Defold sample game built as a starting point and guide for making web games for Poki.
The project contains:
- a complete 3D space shooter game with missions with core gameplay loop, result screens, upgrades shop, pause and settings,
- browser-specific settings and foundations such as Poki SDK, focus handling, audio, saves, touch input, mouse, keyboard and gamepad support, and Live Update setup. You can change the core game and still use the basics of the Poki integration.
- a set of good practices and tips for Poki developers. They describe different aspects of web game development and provide useful knowledge for developers wanting to release a game on Poki and pass the required tests without much friction.
Select Project → Build.
The game will open and show the first Poki Dev Tips selection - switch the tips with arrow buttons or keys. Close the popup with Esc/P. From now on you can open it again in different game contexts using the P key or by clicking the Poki logo in the bottom-right corner. Poki Dev Tips are available in each part of the game, including the core gameplay loop, pause screen and shop.
When you close the popup, the game is still in a paused mode, waiting for first input.
| Action | Keyboard | Mouse | Gamepad | Touch |
|---|---|---|---|---|
| Move | A/D or Left/Right | Drag horizontally | Left stick | Virtual joystick |
| Fire / confirm | Space key | Left button | Bottom button (e.g. Xbox A) | Fire button |
| Pause / back | Esc key | - | Upper button (e.g. Xbox Y) | Pause button |
| Open Poki Dev Tips | P key | Poki logo | - | Poki logo |
| Preview touch controls on desktop | U key | - | - | - |
When you reach the objectives of each mission, you see the win (or fail in the other case) screen pop-up. Gameplay is paused again and you can proceed to the shop screen with upgrades, new ships and skins.
You can always open the Poki Dev Tips for the current context or pause the game using the controls above.
On the pause screen, you can change the language, toggle sound, view the credits or resume the game. Confirm the selected language with Space, the bottom gamepad button or a click.
Desktop builds are useful when working on gameplay, but you should also test the game, SDK events and ads in HTML5.
Click Project → Build Poki HTML5
Game will be build and opened at Poki Inspector in the default web browser.
Try Rewarded Ads. Switch tabs during play, and check sound and pause state when returning. Test touch controls (on desktop you can trigger the touch virtual joystick with the U key).
The project has four main parts:
- Game related code, collections, resources, audio catalogs, fonts, etc.
- Shared common services for audio and input.
- Reusable application services e.g. for Poki, ads, context and time control.
- A separate Learn section with Poki developer in-game tips.
The game starts from app/collections/bootstrap/main.collection, which is generally a good point to start looking at the project structure.
main.collection
├── app/ platform lifecycle, Poki, ads, input, audio and persistence
├── game/ Starbreaker rules, runtime, screen layouts and game-specific GUI
├── ui/ reusable GUI widgets, popup behavior, colors and input helpers
└── learn/ optional in-game Poki development guide
The reusable platform layer in app/ owns application-wide services. The Starbreaker implementation in game/ attaches itself to that layer through game/modules/bootstrap/entry.lua. Screen layouts, popup collections and GUI scripts live with the game because they implement Starbreaker's mission HUD, mothership, pause and result flows. The shared ui/ directory contains reusable Druid widgets and helpers used by game screens and Learn. When adapting the sample, replace the game implementation and reuse the platform services and shared UI.
| Path | Responsibility |
|---|---|
| app/ | Reusable app controller, Poki integration, shared context/time services and sample UI sound catalog. Its main.collection composes this whole sample. |
| assets/ | Art, audio, fonts, atlas and font definitions, models and Particle FX files. |
| common/ | Shared audio service and client code, input helpers and math utilities used by both app and game. |
| doc/ | Images and screenshots for documentation purposes only. |
| game/ | Game entry, gameplay, screen hosts, GUI layouts and scripts, screen collections, audio, logic, shop, profile and deferred asset configuration. |
| input/ | Input bindings. |
| learn/ | Special separated section with Poki developer tips pop-ups. It can be removed by deleting learn/ and its one collection instance from app/collections/bootstrap/main.collection. |
| render/ | Rendering pipeline, materials and shaders. |
| resources/ | Translations, display profiles, and texture profiles. |
| ui/ | Reusable GUI templates (Druid widgets), popup behavior, screen input, focus and shared colors. Game-specific layouts and screen collections live in game/. |
There are several external dependencies used - listed in game.project. The choice of used official and community assets is there to simplify the implementation.
| Library | Used for |
|---|---|
| Poki SDK extension | Poki lifecycle, device info, and the Poki editor command. |
| Ads Wrapper | Commercial and rewarded ads through its Poki adapter. |
| Monarch | Loading and switching game screens and pop-ups. |
| Druid | GUI buttons, widgets, menus handling. |
| Defold Event | Local gameplay signals for hits, sound, VFX, and HUD updates, also used by Druid. |
| Lang | Translations and language switching. |
| Saver | Game profile, progression and settings (language, sound) saved state. |
| HTML Loader | Custom loading progress display in HTML5 builds. |
Bootstrap → Mission → Result → Shop → Next mission
The game object in app/collections/bootstrap/main.collection attaches game/modules/bootstrap/entry.lua to the reusable app controller. app/collections/bootstrap/main.collection also lists Starbreaker's screens, sounds, font support and deferred assets.
Those instances are the project's composition point: when you want to use the base with another core game, you can replace the instances there. The app controller and platform services should stay in app/.
Poki calls are separated into poki_service.lua.
To trace how the code is handling a run, read the following files:
- entry.lua attaches the game and reacts to application lifecycle events.
- session_flow.lua coordinates transitions between missions, results and the shop.
- gameplay.script owns a running mission.
- combat_runtime.lua updates its actors and combat presentation.
- mission_state.lua and combat_rules.lua contain the underlying mission rules.
Game-specific screens and interface code live in game/. Reusable widgets and UI helpers live in ui/. Edit level_config.lua for predefined missions and levels.lua for generated missions.
Change config.lua for stats and progress.lua and profile.lua for saved progress and purchases.
From there, you can experiment with new actors such as enemy ships and projectiles.
- Edit render/ to change the render pipeline, materials and shaders.
- Edit sky.go and background.fp to change the camera-relative background and its screen-space gradient.
- Edit world_visuals.lua and planet_variants.lua to change the background planets.
- Replace art in assets/atlases/ and models in game/resources/models/. Use the existing resource paths or update the components that reference them.
- Replace the gameplay-specific code, screen layouts, collections and assets in
game/. Keep or adaptui/for reusable widgets and helpers. - Keep or adapt
app/when you want to retain Poki lifecycle handling, ads, focus, saves, shared input and audio services. - Keep main.collection as the composition point between the reusable application layer and your game.
- Remove
learn/and its collection instance frommain.collectionif you do not want the embedded Poki guide. - Test platform behavior in Poki Inspector after replacing the game, especially first input, focus changes, pause/resume and ad callbacks.
- Texture compression and atlas limits: the UI atlas uses BasisU Medium compression with mipmaps disabled and a 1024 px maximum texture size. The small VFX atlas remains uncompressed to avoid runtime transcoding overhead and uses a 256 px maximum texture size. These settings are defined in
starbreaker_texture_profiles.texture_profiles. - Deferred asset loading: optional fonts and music are kept out of the initial gameplay payload and loaded through one shared Live Update ZIP. The loader downloads each archive only once, caches and reuses mounted content, retries failed requests, and reports readiness asynchronously.
- Font and collection reuse: loaded deferred collections remain resident. Changing language attaches only the required fallback font and prewarms its text instead of rebuilding or reloading every font collection.
- Screen preloading: the shop screen is preloaded while the mission result is being finalized, reducing the wait during the return transition.
- Fixed-step gameplay simulation: movement, spawning, shooting and combat run in the engine fixed update. Rendering runs at the display update frequency. Gameplay timing is therefore deterministic and independent of rendering frequency.
- Engine-side animation: actor and projectile movement, rotation and visual feedback use Defold animations.
- Event-driven updates: physics events and gameplay messages drive damage, HUD, audio and VFX reactions.
Project is MIT licensed. Check the included asset licenses separately in assets/licenses.