End screen, recap and credits (ui.endscreen) #

Part of the menus and screens guide.

What it is for #

ui.endscreen ends a game without any interface of your own. It opens on the events you list (victory, defeat, missions, the death of the player, the finished phase, the end of the game flow of game.engine), shows the result, a recap (play time, stats read from variables, places and quests of game.engine, lines from other kits) and its buttons, then the credits. It builds one model; every engine draws it (the web player draws it as a ui.webui fragment). The kit needs ui.menu and game.engine: Play again and Main menu go through the menu.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "ui.endscreen" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "ui.endscreen",
                              config: { "onDeath": true, "buttons": ["retry", "menu", "credits", "quit"] } }

With the defaults, emitting game.won opens the victory screen and game.lost the defeat screen.

First example #

<!-- test: kits/game_engine/host/tests/ui_endscreen.rs::an_event_ends_the_game_and_the_screen_pauses_it_once_drawn --> A game emits game.lost. The view then has the result defeat, the title "Defeat" (in French "Défaite"), a recap that starts with the play time and then the score. The game keeps playing until an interface says it draws the screen (attach); then it is paused, and hide resumes it.

{ "op": "call", "service": "ui.endscreen", "method": "view", "args": ["fr"] }

Settings and defaults #

Stat formats: int, number, time, money, percent, text.

Services, events, variables #

• ui.endscreen (service): show(result, stats?) with victory, defeat or anything else for a plain end (false if a screen is already open or a hook cancelled it), hide(), credits(), back(), view(lang) (everything a presenter draws), press(control) (keyboard or gamepad control; answers navigate, back, activate:<button> or none), activate(id), navigate(delta), stats(lang), registerStats(capability), result(), elapsed(), loading(lang), attach().
• ui.endstats (capability): a kit that exposes endStats(lang) returning [{ id, label, value, format? }] and calls ui.endscreen.registerStats("<capability>") gets its lines in the recap.
• endscreen.shown (event): the screen opened, payload { result, time }.
• endscreen.screen (event): the screen changed, payload { screen, from } (end, credits, none).
• endscreen.action (event): a button was activated, payload { action, result } (result is null when the credits were opened alone).
• Variables: endscreen.screen, endscreen.open, endscreen.result, endscreen.time, endscreen.focus. A kit that sets endscreen.title and endscreen.text before the end replaces the heading and the message.
• Listens to: game.won, game.lost, game.phase, mission.completed, mission.failed, player.died, engine.flow.ended (won is a victory, lost a defeat, anything else a plain end), engine.flow.restarted, engine.scene.entered, save.loaded, asset.preload.progress, asset.preload.phase.

Hooks and modding #

• Hook endscreen.show: payload { result, trigger, mission, time }; result is mutable (victory, defeat, end) and the hook is cancellable. trigger is show for a call, else the topic of the event. Runs on the web and Rust hosts.
• A mod may change victoryEvents, defeatEvents, missions, onFinished, onDeath, showTime, stats, buttons, the titles and texts, creditsSpeed, pauseGame and loadingLine. The credits belong to the authors and are not moddable.

Engines #

Web, native, Godot, Unity and Unreal share the same model. Godot and Unity draw it in the style of their menu; Unreal uses a widget class you can replace with EndWidgetClass.

When it does not do what you expect #

• The screen never opens: no event of victoryEvents or defeatEvents, no mission in missions and no show() call reached it, or a tap of endscreen.show cancelled it.
• A stat is missing: its variable does not exist yet when the screen opens.
• Play again does nothing: ui.menu is not installed.
• The game keeps running behind the screen: nothing called attach yet, or pauseGame is false.

Limits #

One screen at a time: show returns false while another is open. The recap only reads variables and the lines kits register.

Versions #

Kit 1.5.0 (adds loadingLine). Service ui.endscreen 1.2.0, capability ui.endstats 1.0.0.