getting_set_up.md

Getting set up

I will not lie, this is a complex framework! Hopefully it's external API isn't too convoluted, but still, probably the easiest way to get set up is to copy the example app, and then adjust it to fit your needs.

• Set up Scaffolder
  • https://github.com/snoringcatgames/scaffolder/blob/master/docs/getting_set_up.md
• addons/scaffolder
  • Add the Scaffolder library to your addons/ folder.
  • This is a framework that provides assorted general-purpose infrastructure that can be useful for adding a bunch of app boilerplate that you may or may not want for your game.
  • Surfacer currently depends on this additional framework.
  • See the Scaffolder README for details on setting it up.
• addons/surfacer
  • Add the Surfacer library to your addons/ folder.
• Su
  • All of the Surfacer functionality is globally accessible through properties on the Su AutoLoad.
  • The Su AutoLoad is automatically registered.
  • "Su" is short for "Surfacer".
• app_manifest
  • Define configuration parameters for Scaffolder and Surfacer.
  • There are a lot of parameters you can adjust here.
  • Most of these parameters are for Scaffolder.
  • Probably the easiest way to get started with this is to copy/paste/edit the pre-existing app-configuration from the Squirrel Away example app.
• Sc.run(app_manifest)
  • Configure both the Surfacer and Scaffolder frameworks by calling Sc.run(app_manifest) as early as possible in your application.
• Include *.json under "Filters to export non-resource files/folders" in your export settings.
  • Platform graphs can be pre-calculated and saved in JSON files.

NOTE: The Scaffolder framework is big. It probably has a lot of stuff you don't need. Also, it probably structures things differently than you want. You should be able to either hide or ignore the bits from Scaffolder that you don't want. Ideally, Surfacer shouldn't depend on Scaffolder. But decoupling these frameworks hasn't been a priority yet. Sorry!

Creating a level

In order to create levels, you'll need to override a few classes from Surfacer.

Probably the easiest way to get started with this is to copy/paste/edit the pre-existing level class from the Squirrel Away example app.

• SurfacerLevel.
• SurfacesTilemap:
  • You will need to instance SurfacesTilemap as a sub-scene in order to define the shape of the collidable surfaces your level.
• SurfacerLevelConfig:
  • You will need to sub-class SurfacerLevelConfig and reference this in your app_manifest.
  • This defines some metadata for each of the levels in your game. For example:
    • name: The display name for the level.
    • sort_priority: The level's position relative to other levels.
    • unlock_conditions: How and when the level is unlocked.
    • platform_graph_character_category_names: The names of the characters that might appear in the level. A platform graph will need to be calculated for each of these characters.

Creating a character

In order to create a new character type, you'll need to override a few classes from Surfacer.

Probably the easiest way to get started with this is to copy/paste/edit a pre-existing character from the Squirrel Away example app.

• SurfacerCharacter
  • This defines how your character reacts to input and decides when and were to navigate within the level.
  • Required children:
    • MovementParameters
    • ScaffolderCharacterAnimator
    • CollisionShape2D
  • collision_detection_layers
    • This helps your SurfacerCharacter detect when other areas or bodies collide with the character.
    • The default PhysicsBody2D.collision_layer property is limited, because the move_and_slide system will adjust our movement when we collide with matching objects.
    • So this separate collision_detection_layers property lets us detect collisions without adjusting our movement.
  • ProximityDetector
    • This helps your SurfacerCharacter detect when other areas or bodies enter or exit the proximity of your character.
    • You can declare these as children in your SurfacerCharacter scenes.
    • You can configure the shape used to define the proximity range.
• ScaffolderCharacterAnimator
  • This defines how your character is rendered and animated.
  • Surfacer makes some opinionated assumptions about how this will be set-up, but you can probably adjust or ignore some of this to fit your needs.
  • uses_standard_sprite_frame_animations
    • Set this export property to true if you want to set up all of the animations for this character by changing the frame property on a corresponding Sprite.
    • If this is enabled, then the ScaffolderCharacterAnimator will expect there to be a one-to-one mapping between immediate-child Sprites and animations in the AnimationPlayer, and these matching animations and Sprites will need to share the same names.
  • animations
    • This Dictionary is auto-populated with keys corresponding to each animation in the AnimationPlayer.
    • You can configure some additional state for each of the animation configs in this dictionary, such as the default playback speed for the animation, and the name of a Sprite to automatically show when starting the animation.
• MovementParameters
  • This defines how your character will move.
  • There are a lot of parameters you can adjust here.
  • You can adjust these parameters within the editor's inspector panel.

Still not working?

See the Scaffolder's Still not working? docs.