Scenária

A JavaScript scene editor for Box2D with behavior programming

Table of contents

• Examples and links
• Quick glossary
• The enviroment
• World
• Entities
• Joints
• Behavior
  • Value holders
  • Entity filters
  • Actions

Examples and links

First things first, here’s a link to the newest deployed version of the editor: https://jkbmat.github.io/bakalarska-praca-dist/.

And here’s some examples of Scenária in action:

• Voleyball
• Pong
• Weird Pong with dampened weld joints

Controls: WASD and arrow keys

Quick glossary

• Entity is a combination of Box2D’s body, shape and fixture. Scenária doesn’t support entities with multiple shapes. The workaround for this issue is to use weld joints.
• Joint holds two entities together and defines their interaction

The enviroment

Here’s how the editor looks once it’s freshly started:

The main sections are:

1. Workspace
   • The place for entity and joint manipulation
2. Contextual sidebar
   • Shows information about the currently selected object
   • Can be resized
3. Entity list
   • Shows a list of all existing entities, their colors and types.
   • Allows for quick selection of an entity
4. Toolbar
   • Contains elements controlling the enviroment
   • Start/Stop button controls the running state of the simulation
   • Save/Load buttons allows the user to save or load scenes to the local machine or the internet
   • Remove all button removes all entities and joints from the scene
   • Undo/Redo buttons step through scene history one step backwards/forwards
   • Collision groups button sets which collision groups should and should not interact. More on this in section Entities.
   • Tool buttons
     • Select tool is used for selecting and repositioning entities and joints
     • Rectangle and circle tools are used for creating new entities with their respective shapes
   • Joint buttons are used for creating new joints. More on this in the section Joints
   • Zoom slider controls the zoom level of the enviroment
   • Language chooser allows changing the editor’s language
     • Language files are located in the folder /app/translations/. Feel free to translate the editor to any language of your choice!

World

If no joints or entities are selected, the contextual sidebar shows information about the simulation world.
Here you can set the gravity vector and camera style.

Camera can be either:

• Locked on point: Static
• Locked on entity: Always centered on an entity of your choice

Entities

To add a new entity to the simulation, simply choose the desired tool and create the entity in the work space using drag & drop. It will be assigned default attributes and a random color.
Each entity is assigned a layer and a collision group. Layers determine the order in which entities are drawn. Collision groups determine which entities should interact with which other entities.
The Collision groups window, accessible form the toolbar, is a place to define collision group interaction.

Collision groups 2 and 3 will now no longer interact

Aside from layer and collision group number, an entity has the following attributes:

• ID: A name, so to speak
• X/Y position
• Width/Height
• Rotation
• Fixed rotation: The entity’s rotation will stay fixed
• Restitution: “Bounciness” of the entity.
• Friciton
• Density: Combined with its dimensions, density determines an entity’s weight
• Precise collision checking at high velocities: Also called the bullet flag. Improves collision checking of quick moving entities, so they don’t pass through thin entities. This is hovewer more computation-intense.
• Color
• Body type
  • Dynamic: The basic entity type
  • Static: Immovable entity. Has infinite mass and cannot be moved by any interactions, impulses or forces.
  • Kinematic: Same as the static body type, but can be interacted with using impulses and forces. It also has infinite mass, so interaction with static entities is ignored (Interaction of two objects with infinite mass is not defined in Newtonian physics).

Joints

Joints bind two entities together and change how they behave. To create a joint, first click on the joint’s button in the toolbar. A dialog will appear in the contextual sidebar, where the connected entities need to be chosen.

After creating the joint, the following attributes can be changed:

• ID: Name of the joint. Unused as of yet.
• Connected entities should collide
• Connected entities and the relative positions of the joint

Each type of joint can also have additional attributes:

• Weld joint: Holds two entities together at fixed distance and angle
  • Damping frequency: How often the entities’ positions should be corrected. 0 is fixed positions, otherwise the lower, the bouncier.
• Revolute joint: The two entities rotate about a common point (imagine a hinged door).
• Rope joint: Constricts maximal distance between two entities
  • Maximum rope length

Behavior

The real strength of Scenária lies in editing Entities’ behaviors. The behavior editor can be accessed by clicking on Set behavior button in the contextual sidebar when an entity is selected.

The behavior system is strongly typed using the following types:

• boolean
• number
• string
• action
• entityfilter
• literal

A behavior comprises of two parts:

• One condition: (type: boolean) Is checked on every frame
• One or more actions: (type: action) If the condition is fulfilled, all of the behavior’s actions are carried out.

An entity can have any number of behaviors.

The full list of implemented commands is as follows:

Value holders

You can use keycode.info to find keycodes of buttons.

Entity filters

All entity filters are of type entityfilter. All entity filters except thisEntity, allEntities and filterById take an entityfiler as the first argument, which they then filter further.

Actions

Actions are executed when their behavior’s condition is fulfilled. All actions are of type action.