Skip to content

Code Structure

Jump to bottom Edit New page
Jonathan Chung edited this page Feb 12, 2014 · 6 revisions

Introduction

Stencyl's engine is written on top of OpenFL, a popular Haxe framework that replicates the Flash API. In order to understand the engine, it helps to know Haxe or ActionScript 3.

Stencyl is heavily reliant on Box2D, a popular physics library used in many games.

Prerequisites

Here's what you need to know to understand the Stencyl engine.

  • Haxe or ActionScript 3
  • Knowledge of Box2D is extremely helpful if working with physics
  • Basic knowledge of Flash API's fundamentals like the display tree, sprites, etc.

IDEs

Developing in Haxe is still somewhat behind other environments. Here are the best options which have Haxe integration built in (code completion, syntax highlighting).

  • Sublime Text 2
  • Flash Develop (Windows only)
  • Mono Develop
  • EclipseHX

Developing in a plain text editor is another fine choice.

Basics

Scenes

Scenes are the game's worlds. They consist of terrain (in the form of tiles), actors, backgrounds and some behaviors.

Actors

Actors are game objects. Every actor is associated with a Box2D body, a set of animations and some behaviors that bring it to life.

Behaviors

Behaviors are configurable, reusable components that add logic to Actors or Scenes.

The Game Loop

Stencyl attempts to run every game at 60 FPS from a graphics rendering perspective. Game logic actually runs in fixed steps of 10ms (equivalent to 100 FPS) in order to get the physics engine to run predictably. This leads to some frames having more steps than others. Excess time is carried over to the following frame.

Games can abuse (modify) the step duration to alter the game's perceived speed. Quantum Corps is an example of this.

Here's the order in which things execute within one STEP of the game loop.

  • Update Tweens
  • Mark physics objects as on/off screen
  • Update Mouse / Trigger Mouse Events
  • Update / Trigger Timed Tasks (do later, do every N seconds)
  • Update Keyboard / Trigger Keyboard Events
  • Native Mobile Events
  • Update Physics
  • Update Regions
  • Synchronize Animations
  • Update Actors
  • Update Animated Tiles
  • Update Transitions
  • Update Camera
  • Poll Input (Mouse, Keyboard)

Outside a step, here's what happens for each FRAME of the game loop.

  • Step the game an appropriate number of times.
  • Remove dead/recycled actors.
  • Draw.

Rendering and Scaling

Graphics in Stencyl games must adapt to a wide variety of formats from web/desktop to iOS and Android devices.

To do this, we have our users import graphics at "4x" the base resolution by default. From that, we generate sets of "1x", "1.5X", and "2x" graphics. When a game is loaded up, it checks the device type and screen resolution in order to choose the proper graphics set to draw with.

In effect, this allows a game to be designed in logical "point" units as opposed to physical "pixel" units. In layman's terms, the user always designs for "1x" and with only one small exception (4" iOS devices such as iPhone 5), doesn't care about what happens on an end user's device.

If for whatever reason, it must be known what the current scale is, this can be obtained by grabbing this constant.

Engine.SCALE

Key Files (relative to Source/)

These are the files that you're most likely to edit or view.

GLOBAL

  • Universal.hx - Entry point for a game. Sets up the screen / scaling options.
  • com/stencyl/Engine.hx - Holds the "game loop" and is the center for pretty much everything.
  • com/stencyl/Data.hx - Controls initial loading of data.
  • com/stencyl/Input.hx - Controls all user input.

BEHAVIORS

  • com/stencyl/behavior/Script.hx - Holds the public API for all behaviors.
  • com/stencyl/graphics/G.hx - The custom drawing API.

KEY MODELS

  • com/stencyl/models/Actor.hx - The Actor class.
  • com/stencyl/models/SoundChannel.hx - Controls Sound playback. Relevant for those tackling sound problems/deficiencies.

Data Formats (as of Stencyl 3.0)

Data formats are relative to what the game engine sees. This may differ slightly from what Stencyl sees in a "source" project.

Stencyl stores its game data primarily in XML. These are the files you'll find.

  • Assets/data/game.xml - Properties, controls, groups, game attributes, atlases and other game-wide data.
  • Assets/data/behaviors.xml - General behavior properties.
  • Assets/data/resources.xml - Properties for all game resources.
  • Assets/data/scenes.xml - Scene listing.
  • Assets/data/scene-[SCENEID].scn - Scene terrain data.
  • Assets/data/scene-[SCENEID].txt - Scene terrain data (for HTML5).
  • Assets/data/scene-[SCENEID].xml - All data for a scene except terrain.

The best way to learn the internals is to peek at the source of the data format readers, rather than trying to pick apart the files themselves. These are located under the com/stencyl/io package.

For the future, we'd like to break up the data into more individual files in order to make it more fault tolerant and shareable.

Add a custom footer

File Formats

Clone this wiki locally