Skip to content

Application scaffolding and utility functionality for Godot games.

License

Notifications You must be signed in to change notification settings

SnoringCatGames/scaffolder

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Scaffolder

The Scaffolder icon, showing construction scaffolding

Example app

Godot Asset Library

Opinionated scaffolding and utilities for games in Godot.


NOTE: Consider this a pre-alpha release.

  • This framework still has many rough edges, is still changing a lot, and is possibly a lot more inflexible than you would want (it makes a lot of assumptions about how you've structured your app).
  • See the Still not working? docs for more context into how difficult this may be for you to use.

Some features include:

  • Configurable UI and camera scaling to adapt to the current viewport.
  • Optional analytics based on the proprietary third-party Google Analytics service.
  • Optional automatic crash log reporting based on the proprietary third-party Google Cloud Storage service.
  • Screen layout and navigation.
  • Lots of useful utility functions (e.g., ScaffolderTime, Geometry, DrawUtils, Audio).
  • A widget library (e.g., AccordionPanel, LabeledControlList)

Some of the GUI elements that Scaffolder makes it easy to set up and use.

GUI scaling depending on the screen size.

⚙️ Getting set up

See this separate doc for getting your project set up to work with Scaffolder.

✨ Features

Lots of useful utility functions

It might just be easiest to scroll through some of the following files to see what sorts of functions are included:

A widget library

For example:

Viewport scaling

This framework handles viewport scaling directly.

This provides some powerful benefits over Godot's standard behaviors, but requires you to be careful with how you define your GUI layouts.

Handling camera zoom

This provides limited flexibility in how far the camera is zoomed. That is, you will be able to see more of the level on a larger screen, but not too much more of the level. Similarly, on a wider screen, you will be able to able to see more from side to side, but not too much more.

  • You can configure a minimum and maximum aspect ratio for the game region.
  • You can configure a default screen size and aspect ratio that the levels are designed around.
  • At runtime, if the current viewport aspect ratio is greater than the max or less than the min, bars will be shown along the sides or top and bottom of the game area.
  • At runtime, the camera zoom will be adjusted so that the same amount of level is showing, either vertically or horizontally, as would be visible with the configured default screen size. If the screen aspect ratio is different than the default, then a little more of the level is visible in the other direction.
  • Any annotations that are drawn in the separate annotations CanvasLayer are automatically transformed to match whatever the game-area's current zoom and position is.
  • Click positions can also be transformed to match the game area.

Handling GUI scale

  • At runtime, a gui_scale value is calculated according to how the current screen resolution compares to the expected default screen resolution, as described above.
  • Then all fonts, styleboxes, and icons—which are registered with the scaffold configuration—are resized according to this gui_scale.
  • Then the size, position, and scale of all GUI nodes are also updated accordingly.

Constraints for how you define your GUI layouts

TODO: List any other constraints/tips.

  • Avoid custom positions, except maybe for centering images. For example:
    • Instead of encoding a margin/offset, use a VBoxContainer or HBoxContainer parent, and include an empty spacer sibling with size or min-size.
    • This is especially important when your positioning is calculated to include bottom/right-side margins.
  • Centering images:
    • To center an image, I often place a TextureRect inside of a Control inside of some time of auto-positioning container.
    • I then set the image position in this way: TextureRect.rect_position = -TextureRect.rect_size/2.
    • This wrapper pattern also works well when I need to scale the image.
  • In general, whenever possible, I find it helpful to use a VBoxContainer or HBoxContainer as a parent, and to have children use the shrink-center size flag for both horizontal and vertical directions along with a min-size.

Analytics

This feature depends on the proprietary third-party Google Analytics service.

  • Fortunately, Google Analytics is at least free to use.
  • To get started with Google Analytics, read this doc.
  • To learn more about the "Measurement Protocol" API that this class uses to send event info, read this doc.
  • To learn more about the "Reporting API" you could use to run arbitrary queries on your recorded analytics, read this doc.

"Privacy Policy" and "Terms and Conditions" documents

If you intend to record any sort of user data (including app-usage analytics or crash logs), you should create a "Privacy Policy" document and a "Terms and Conditions" document. These are often legally required when recording any sort of app-usage data. Fortunately, there are a lot of tools out there to help you easily generate these documents. You could then easily host these as view-only Google Docs.

Here are two such generator tools that might be useful, and at least have free-trial options:

DISCLAIMER: I'm not a lawyer, so don't interpret anything from this framework as legal advice, and make sure you understand which laws you need to obey.

Automatic error/crash reporting

This feature currently depends on the proprietary third-party Google Cloud Storage service. But you could easily override it to upload logs somewhere else.

Screen layout and navigation

  • You can control transitions through Sc.nav.
  • It is easy to include custom screens and exclude default screens.
  • Here are some of the default screns included:
    • Main menu
    • About
    • Settings
      • Configurable to display checkboxes, dropdowns, or plain text for whatever settings you might want to support.
    • Level select
    • Game/level
    • Pause
    • Notification
      • Configurable to display custom text and buttons as needed.
    • Game over

📃 Licenses

The Scaffolder icon, showing construction scaffolding