Title - AbstractPolygon/vcs-game-maker-absply GitHub Wiki

The Title tab holds one or more title screen pages — full-screen bitmap graphics drawn with the Titlescreen Kernel, typically used for a title/menu screen. Each page fits up to ~85 double-line rows or ~170 single-line rows.

Toolbar

See the Graphic Editor Toolbar page for a description of graphic editing tool functionality.
Quick color palette — pick a color here to paint with it directly in a graphic's color strip. Shared with the Background and Sprites tabs' quick colors.

Export title screen / Import title screen — saves the selected page, with all its graphics, to a .vcstitle file, or loads one from a file as a new page. Importing a page whose name matches an existing page replaces that page instead of adding a second one.

Graphics

Each page holds one or more stacked graphic cards, drawn top to bottom in the order they'll be displayed in by the Titlescreen kernel. Click Add graphic to add one, picking its kernel type:

48x1 — 48 pixels wide, 1 scanline per row (half-height pixels), a single color for the whole graphic.
48x2 — 48 pixels wide, 2 scanlines per row (square-ish pixels), a separate color per row.
96x2 — 96 pixels wide, 2 scanlines per row, a separate color per row.
Player sprites — draws up to 2 Player 0/1 hardware sprites.
Score — draws the game's 6-digit score. See "Score" below.
Space — a blank spacer row with no image, for laying out gaps between graphics.

The kernel supports 8 pre-built copies of each bitmap type (48x1/48x2/96x2). That pool of 8 is shared across every page in the project - once all 8 copies of a type are used up across all pages combined, no more graphics of that type can be added anywhere in the project. Player sprites and Score are currently limited to a single card project-wide - only one of each can exist across every page combined.

Each bitmap graphic holds one or more frames of animation:

The pixel grid itself, resizable in height via the Graphic Editor Toolbar's "Set height" tool.
A color strip (48x2/96x2: one color per row; 48x1: a single color, shared across every frame on the card) - click a row's swatch to open the palette, or click-and-drag across rows to paint several at once. Clear resets both the pixels and the colors back to their defaults.
Duration — (only shown once a card has more than one frame) how many game frames this frame is shown before advancing to the next one. It cannot be lower than 1.

Copy this frame's image / Paste copied image onto this frame — copies (or pastes) the pixel data, row colors and picture background together.

Copy this frame's row colors only / Paste copied row colors only onto this frame (the copy and paste icons with a small "C", in the frame's top-right corner) — move just the row colors from one frame to another.

Drag a frame anywhere except the drawing, its fields and its buttons to put the frames in a new order.

Delete this frame (or select it and press Delete) — only shown when the card has more than one frame.

Window height (0 = no scrolling) — sits above the frames; set it smaller than one frame's height to enable scrolling (see below).

Duplicate this card — adds a copy of the whole graphic, with all its frames.

Delete this graphic (or select it and press Delete) — asks for confirmation.

Click Add animation frame (the + to the right of a card's frames) to add a new frame. With a frame selected it is a copy of that frame (including its Duration and picture background), placed right after it; otherwise it is a copy of the last frame, added at the end. Click the chevron in the top-left corner to collapse a graphic card. Drag the strip at the top of a card to reorder graphics within their page.

Import card frames from image files (the image-stack icon, top-right of a bitmap card) picks several image files at once and imports each as a new frame, one image per frame, sized to the card's width. Files with a number in their name (e.g. frame1.png, frame2.png) are ordered by that number; otherwise they're used in whatever order they were selected in. A Replace frames switch in the popover controls whether the imported frames land alongside the card's current frames or replace them outright. With it on, Keep row and box colors gives each new frame the row colors and picture background of the frame it replaces (frame 1 takes frame 1's, and so on, the last old frame's for any extra frames).

To import frames from a sprite strip image plus an Aseprite-exported .json, select a card first, then use Import from Aseprite in the Graphic Editor Toolbar above - unlike the Sprites tab, a .json with more than one frame tag is rejected, since a title screen card only supports a single animation.

Animation

A graphic with more than one frame plays back automatically - each frame's Duration (in game frames, same as a Sprites tab animation) controls how long it's shown before advancing to the next, looping back to the first once it reaches the end. No trigger block needed - it starts advancing the moment the page is drawn, and only moves while its page is the one being drawn.

Under Window height, a Play animation once switch (shown once a graphic has more than one frame, off by default) makes the graphic play through once and stay on its last frame instead of looping. The blocks below can still start it again.

A graphic's frame Durations can add up to at most 255 in all; the build stops with a message naming the graphic when they add up to more.

To save ROM, a 48x2 graphic that repeats one picture under different row colors stores the picture once and each different row color list once, identical pictures and identical color lists on different graphics are stored once, and blocks that still point at a deleted graphic cost nothing. 96x2 graphics only share a frame when both its pixels and its colors match.

A graphic's pixels are drawn in the proportions the emulator uses (about 0.88 wide to 1 tall for 48x2 and 96x2, about 1.77 to 1 for 48x1), so a circle looks round in the editor and on screen.

Frames on the same card should stay a uniform height, same as a Sprites tab animation - resizing one frame's height offers to apply that same resize to every other frame on the card at once, keeping them in sync.

Picture background (48-wide graphics)

A 48x1 or 48x2 graphic can have a colored area behind its picture, drawn with the playfield. Each frame can have a different one:

A swatch under the row color bar sets the picture background color.
A row of 12 blocks under the frame, lined up with the pixels above it (each block covers 4 pixels), switches the color on (shown in the picture background color) or off (shown in the page's color) behind that part of the picture. The right half of the screen mirrors the left, so blocks that mirror each other switch together.
The canvas previews the result in the empty pixels of the frame.
Clearing a graphic's colors also puts the picture background colors back to the page's color.

When the frames of an animated graphic have different picture backgrounds, the background changes as the animation moves from one frame to the next. Anything set with the blocks below lasts until the next frame starts.

Player sprites

A "Player sprites" card draws up to 2 hardware sprites - pick Player 0 animation and/or Player 1 animation from a dropdown of your Sprite animations.

Each also has:

Fallback color — used only when the chosen animation doesn't have per-row sprite colors turned on (Options tab).
Window height — how tall the card's draw region is, in scanlines (independent of either sprite's height).
Scanlines per pixel row — 1 (sharper, half-height pixels) or 2 (roughly square pixels).

An animation with more than one frame plays by itself, using each frame's duration. An animation with one frame stays where it is. Position each sprite with the ordinary Player 0/1 set X/Y blocks (Actions tab) - it's the same hardware sprite, just drawn by the title screen kernel instead of the normal game kernel while a title screen is showing. Jump to a frame, and choose whether it then loops or plays once, with Set title screen player sprite frame to (see below).

Score

A "Score" card draws the game's 6-digit score, using whichever font is currently selected on the Score tab and colored via the Score category's Score set color to block (Actions tab) - there's nothing to configure on the card itself. The Options tab's "Show remaining CPU cycles as the score" (cyclescore) has no effect here - it only overlays the standard game kernel's score drawing, which a title screen never calls.

Scrolling

Give a graphic a "Window height" smaller than one frame's height, and only that many rows of the current frame are drawn on screen at once. Use the Set title screen scroll position of [graphic] to [n] block at runtime to move the visible window through that frame - 0 shows the very top, increasing it scrolls further down. Only graphics with scrolling enabled appear in that block's dropdown. To start at any position, set it first with that block; the scroll blocks below move from wherever it is.

Scroll title screen graphic [name] [Up/Down] by [n] moves the window by n rows. With stop at edge checked (the default), it stops when the top of the graphic reaches the top of the window (offset 0) or the bottom of the graphic reaches the bottom of the window. For a graphic with several animation frames the edge is that of the frame currently showing. When title screen scroll of [name] reaches the Top/Bottom runs its blocks once each time a stop-at-edge scroll lands on that edge.

Scrolling works alongside animation (above) on the same card - the card keeps cycling through its frames automatically on its own schedule while the scroll position independently slides the window within whichever frame happens to be showing.

Using title screens from your blocks

On the Actions tab, the Title category has blocks for:

Draw title screen — draws the chosen page. Call this every frame for as long as you want it shown (e.g. from "Title screen update").
Set title screen scroll position of [graphic] to [n] — scrolls a graphic that has scrolling enabled.
Scroll title screen graphic [graphic] [Up/Down] by [n] (with a stop at edge checkbox) — moves a scrolling graphic from its current position.
When title screen scroll of [graphic] reaches the [Top/Bottom] — runs once when a stop-at-edge scroll reaches that edge.
Set title screen graphic [graphic] to frame [n] hold it [ ] then [loop / play once] — jumps a graphic with several frames to a frame (0 is the first). With "hold it" off the graphic goes on playing from there: "loop" keeps going round, "play once" plays to the last frame and stays there. With it on, the graphic stays on that frame until another block of this kind sets it going again.
Animate title screen graphic [graphic] [forward / in reverse] then [loop / play once] — starts the animation of a graphic with several frames from the beginning: forward from the first frame, or in reverse from the last one, and lets go of a graphic a "hold it" block was holding. Looping goes round again; "play once" stays on the last frame reached (the first frame, in reverse). It acts as a trigger: it starts the animation when it runs after a frame in which it did not, so an "if" that stays true does not start it over every frame, and the animation carries on after the "if" turns false.
When title screen graphic [graphic] animation finishes — runs the connected blocks once each time the animation finishes: every time round when it loops, once when it plays once (in reverse, when it reaches the first frame).
Set title screen graphic [graphic] color to [n] — changes the color of a single-color (48x1) graphic.
Set title screen graphic [graphic] picture background to [behind the picture / off / the full width] — switches the picture background of a 48-wide graphic.
Set title screen graphic [graphic] picture background color to [n] — changes its color.
Set title screen background color to [n] / Reset title screen background color — changes the background color of every page while the title screen shows, and goes back to the page colors.
Fade title screen graphic [graphic] color to [color] over [n] frames — fades the color of a 48x1 graphic, or the row colors of a 48x2 graphic, toward the chosen color over roughly that many frames. The fade tables only take ROM when a project uses this block.
End title screen — stops the Title Screen Kernel and shows the regular game screen from the next frame on, while staying in "Title screen update". Only works there; "Title screen start" turns the kernel back on. It can sit anywhere in a stack: the blocks after it still run that frame, and "Draw title screen" blocks do nothing once it has run.
Set title screen player sprite frame to [n] then [loop / play once] — changes which frame of a "Player sprites" card's chosen Player 0/1 animation shows (0 = the first frame), then carries on as chosen.

"Title screen start" puts every color, held frame, picture background and background color changed by these blocks back to what the Title tab says. The title screen's variables share their slots with variables the game only uses while it runs, so the title screen costs the game almost no variables; the game's variables are cleared when the game starts. This includes variables that only the blocks running after "End title screen" use (for example an "if state = 3" stack in "Title screen update" that the state only reaches once "End title screen" has run): those start from zero when "End title screen" runs. Graphics on different pages share variable slots with each other where they can.

The Title Screen Kernel also works with the DPC+ kernel. On DPC+ it needs the memory of some virtual sprites for working bytes, so a project with a title screen has fewer of the freed sprite bytes available as variables (set the virtual sprites on the Options tab to 1 to free the most).

The Titlescreen Kernel moves the sprites' positions around while it draws. When a project has no block that sets or changes where a sprite is (the Player, Missile and Ball X/Y blocks, or a Fire block), gameplay starts with the players, missiles and ball back at the positions a new project begins with.

Drawing a title screen takes over the whole frame itself (vsync/vblank/overscan included) - don't also draw backgrounds/sprites or call "Draw screen" in the same event as "Draw title screen".

See the Actions tab's Title category for every Title block.