Phyard Builder UI Elements
- 1 About Level Editing
- 2 User Interface
- 3 Using Components
- 3.1 Preparation Knowledge
- 3.2 Using Basic Shapes (Circle, Rectangle, Polygon, Polyline)
- 3.3 Using Joints (Hinge, Slider, Distance, Spring, Weld, Dummy)
- 3.4 Using Utility and Preset Shapes
- 3.5 Overview of The Trigger System
- 3.6 Using Trigger Components
About Level Editing
Editing a level is just to create some instances of system defined components in these world scene and adjust the properties of the instances as needed.
Later, we will call an instance of a component as an Entity.
The image above show the initial screen of the phyard builder. It contains 5 areas:
- At the top (red box) is the Main Command Bar.
- Below the main command bar (green box) is the Secondary Command Bar.
- At the left (yellow box) is the Component Create Commands Panel.
- At the bottom (blue box) is the Status Bar.
- The center is the working area, it is called World Scene Area.
Before introducing each part of the interface, we should know there are 3 views:
- Scene Editing View is the initial view. You can create entities and modify their properties in this view.
- Collision Category Editing View is for creating Collision Categories, modifying their properties and creating friend links between collision categories.
- Playing View is for testing the current level.
|Left three commands||Center two commands||Right one command|
|Commands in center left panel||Commands in center right panel|
Load Save Info Clear Entities World Setting Clone Delete Flip Horizontally Flip Vertically Move To Top Move To Bottom
From left to right:
- Go To Entity command. Every entity has an unique id. If there are many entities in the world scene, then it is some difficult to find the entity though a specific id. This command is just to make this job easier.
- You can input more than one ids in the input box.
- When you click the "Go To Entity#" label, the entities specified by the input ids will be selected.
- Show Commands are used to show some special informations.
- Show Entity IDs
- Show Links
- Hide Commands are used to hide some entities so that the world is tidier.
- Hide Invisibles
- Hide Shapes & Joints
- Hide Triggers
- Scale View Commands. The scale range is from 1/16 to 16.
Component Create Commands
There are 3 tabs in the component create commands panel. The first one is General Components Create Commands Panel. The second is Trigger Components Create Commands Panel and the third is More Components Create Commands Panel. Followings are the simple introductions of these create commands.
General Components Create Commands
|Create Rectangle Shape||Create Cirlce Shape|
|Create Polygon Shape||Create Polyline Shape|
|Create Hinge Joint||Create Slider Joint|
|Create Distance Joint||Create Spring Joint|
|Create Weld Joint||Create Dummy Joint|
|Create Force Power Source||Create Torque Power Source|
|Create Linear Impulse Power Source||Create Angular Impulse Power Source|
|Create Camera||Create Text|
|Create Gravity Controller||Create Text Button|
|Create Rectangle Bomb||Create Circle Bomb|
Trigger Components Create Commands
|Create Action||Create Task|
|Create Basic Condition||Create Condition Door|
|Create Entity Assignern||Create Entity Pair Assigner|
|Create OnLevelBeforeInitializing Event Handler||Create OnLevelAfterInitialized Event Handler|
|Create OnLevelBeforeUpdating Event Handler||Create OnLevelAfterUpdated Event Handler|
|Create OnJointReachLowerLimit Event Handler||Create OnJointReachUpperLimit Event Handler|
|Create OnWorldMouse(Click | Down | Up | Move) Event Handlers||Create OnShapeMouse(Click | Down | Up | Move | Enter | Out) Event Handlers|
|Create OnKey(Down | Up | Hold) Event Handler||Create OnEntityInitialized Event Handler|
|Create OnEntityUpdated Event Handler||Create OnEntityDestroyed Event Handler|
|Create OnTwoShapes(Start | Keep | End)Contacting Event Handlers||Create OnWorldTimer Event Handler|
|Create OnEntityTimer Event Handler||Create OnEntityPairTimer Event Handler|
More Components Create Commands
In scene editing view, the status bar will show the followings:
- basic informations of the selected entity.
- mouse coordinates by pixels.
- mouse coordinates by meters.
In playing view, the status bar will show the followings:
- simulation FPS
- simulation steps
- mouse coordinates by meters
- mouse coordinates by pixels.
- mouse coordinates by meters.
There is no status bar in collision category editing view.
As the beginning of the tutorial mentions, designing a level is just to create some entities in the world scene and adjust the properties of these entities as needed.
Component Creation Styles
To create an entity creation process, you should first select a create command on the left component create comands panel.
Currently, there are 3 entity creation process styles:
- mouse press-drag-release style (also called Drag Creation Style) is used in creating rectangles, circles, slider joints, distance joints, spring joints, dummy joints, bombs, gravity controllers, texts and text buttons.
- mouse multi-click style (called Multi-Click Creation Style in short) is used in creating polygons and polylines.
- mouse click style (also called Place Creation Style) is used in creating other components.
Before introduce how to select entities, we should know what is Entity Brothers.
When there are more than one entities are selected, you can make them as Entity Brothers by select the Make Brothes command on the main command bar. In simulating, brother entities will be glued together (no relative translation and rotation between them).
There are 2 selection modes, one is the default mode, the other is called Cookie Mode. You can turn on/off the cookie mode by select the Toggle Cookie Mode command on the main command bar.
Under the default selection mode:
- when you press mouse on an entity, the entity will be selected. At the same time, the selection statuses of old selected entities will be cleared.
- when an entity is selected, all its brothers will be also selected automatically.
Under cookie selection mode:
- when you release mouse on an entity, the entity will toggle selection status. The selection statuses other entities will NOT changed.
- when an entity is selected, all its brothers will be NOT selected automatically.
For both modes:
- you can click on a blank area to cancel clear all selections.
- you can hold CTRL key to avoid clear the selection statuses of old selected entities.
- you can drag a box from a blank area to box select many entities.
Modify Entity Properties
To modify the properties of an entity, you must first select it, then you can press SPACE key or select the Entity Setting Command on the main command bar to open the Entity Setting Dialog. There are some property options in the dialog.
For all entities, there is 'Basic tab panel in the setting dialog. Please read user manual to get the meaning of each option in the dialog.
You can select the Enter Playing View command to play and test the current level in editing. To exit the playing view to scene editing view, select the Exit Playing View command.
Using Basic Shapes (Circle, Rectangle, Polygon, Polyline)
Create Basic Shapes
At the top of general component create command panel is the create shape commands.
The above 4 commands are used to create Basic Shape Components. Now, there are 4 general shape component types: Rectangle, Circle, Polygon and Polyline.
- To create a rectangle component, select the Create Rectangle Command (the above ), move mouse into the working area, then press the left mouse button and drag, when the size of the rectangle is satisfying, release left mouse button.
- Creating a circle component is much like creating a rectangle component, the difference is you must select the Create Circle Command (the above ) firstly.
- To create a polygon component, select the Create Polygon Command (the above ), move mouse into the working area, then click (press then release) mouse at the position of the first vertex of the polygon, then move mouse to the position of the second vertex and click, then the third vertex, .... To finish the creation process, you can click on either the first vertex or the last vertex.
- Creating a polyline component is much like creating a polygon component, the difference is you must select the Create Polyline Command (the above ) firstly.
- The minimal width and height of a rectangle is 2 pxiels.
- The minimal radius of a circle is 1 pixles, or the minimal diameter is 2 pixles.
- A polygon must have 3 vertexes at least.
- A polyline must have 2 vertexes at least.
- In any creating process, you can press ESC to cancel the process.
Modify Properties of Basic Shapes
An instance of a component is called an Entity.
You can change the created shape properties in the shape entity setting dialog. You can select the entity setting command in the main command bar or press SPACE key to open the setting dialog.
For all basic shapes, there are 3 tab panels in the setting dialog: Physics properties setting panel, Appearance properties setting panel and Basic properties setting panel. Please read user manual to get the meaning of each option in the dialog.
There is a Collision Category property for shapes. This property is only for physics shapes (the Enable Physics property is true).
Sometimes, we don't want to 2 physics shapes collide even if they are overlapped visually. To make this possible, the concept of collision category is introduced. You can put the 2 shapes in 2 different collision categories and set the 2 collision categories as friends.
To create collision categories and set categories as friends, you must select the toggle scene editing view / collision category editing view command and enter the category editing view. This main command bar is different in the category editing view:
From left to right, the commands (in the red box) are:
- Create Collision Category
- Delete Selected Collision Categories
- Set The Selected Collision Category Harmonious, all shapes in a harmonious category will not collide with each other.
- Set The Selected Collision Category As The Default Category, when creating a new shape, the shape's collision category property will set as the selected collision category.
- From now on, we will call collision category as ccat.
- There is a default hidden ccat. If no new ccats are created, all new created shapes are put in the hidden ccat. The hidden ccat is not harmonious.
To create a new ccat, first select create collision category command, then click mouse in the center view field.
To set 2 ccats as friends, drag a link from either of the 2 ends of one ccat to the other ccat. Breaking a friend link is the same as creating the friend link.
Create Basic Color Infection (C.I.) Shapes
The phyard builder is evolved from Color Infection Editor, or C.I. Editor. The C.I. editor is used to create Color Infection Levels.
Below the 4 basic shape create commands, there are 6 smaller button to create C.I. shapes. Initially, they are 6 C.I. rectangle create commands. When you click the above general basic shape create commands, the below 6 commands will change correspondingly.
Each of the 6 C.I. shape types has a specific color:
- static type is gray color.
- movable type is blue color.
- infected type is brown color.
- uninfected type is yellow color, uninfected type shapes are infectable.
- dont-infect-me type is green color, dont-infect-me type are also infectable.
- breakable type is pink color
Color Infection Rules:
- when an infectable type shape (yellow or green) contacts with an infected type shape (brown), the infectable shape will become an infected shape.
- when a breakable type shape (pink) is clicked, the shape will be destroyed.
- if any dont-infect-me type shape (green) is infected, the level fails.
- if all uninfected type shapes (yellows) are infected and none dont-infect-me type shapes (greens) are infected, the level is finished.
Using Joints (Hinge, Slider, Distance, Spring, Weld, Dummy)
Below the create shape commands in the create command panel is the Create Joint Commands.
A joint will connect with 2 shapes apply some specific effects on the 2 shapes in simulating. Currently, there are 6 joint types: Hinge Joint, Slider Joint, Distance Joint, Spring Joint, Weld Joint and Dummy Joint.
- A hinge joint attempts to make the 2 connected shapes rotate relative to each other about a fixed axis of rotation (From wikipedia). Here, in 2d world, the axis is perpendicular with the screen and through the hinge anchor point. To create a hinge, select the Create Hinge Joint Command () and place the hinge entity at the position of the rotation axis in the world scene.
- A weld joint attempts to constrain all relative motions between the 2 connected shapes. Creating a weld joint is much like creating a hinge joint, the difference is you must select the Create Weld Joint Command () firstly.
- A slider joint allows for relative translation (but no relative rotation) of two shapes along a specified axis. To create a slider, first select the Create Slider Joint Command (), then press mouse to place the first anchor on the first shape to be connected then move and release mouse on the second shape to be connected to place the second anchor.
- A distance joint attempts to constrain the distance of 2 points on the 2 connected shapes be constant. Creating a distance joint is much like creating a slider joint, the difference is you must select the Create Distance Joint Command () firstly.
- A spring joint acts as a spring connected between the 2 conected shapes. Creating a spring joint is much like creating a slider joint, the difference is you must select the Create Spring Joint Command () firstly.
- As the name hints, a dummy joint applies nothing on the 2 connected shapes. Dummy joints are useful for some APIs. Creating a dummy joint is much like creating a slider joint, the difference is you must select the Create Distance Joint Command () firstly.
Modify Properties of Joints
You can modify the properties of joints in the Joint Setting Dialog.
For detail explanation of joint properties, please see the menaul
You will notice that there are two basic tab panels in the setting dialog. One is for the selected joint anchor. The other is for the joint itself. The reason is joints themselves are not selectable in scene editing view.
All joints have 3 common properties: Collide Connected Shapes, Shape 1 and Shape 2.
- Shape 1 and Shape 2 are the two connected shapes. You can manually assign the two connected shapes for a joint in the joint properties setting dialog. If they are not assigned, the joint will automatically select the shapes under the joint anchor(s) as the two connected shapes. If no shapes are available under the joint anchors, the ground will be selected.
- The Collide Connected Shapes means whether or not the two connected shapes should collide with each other in simulation.
There are some common properties for hinge and slider joints:
- Enable Limits, whether or not enable the relative rotation (for hinges) and relative translation (for sliders) between the two connected shapes.
- Lower Angle and Upper Angle are the two rotation limits for hinges. Lower Translation and Upper Translation are the two translation limits for sliders.
- Enable Motor, whether or not a hinge or slider is a power source.
- Motor Speed, for hinge this is the target rotation speed. For slider this is the target translation speed.
- Max Motor Toque is the max torque a hinge can produce, Max Motor Force is the max fore a slider can produce.
- Back and Forth Between Limits, this properties is only valid when both limits and motor are enabled. It means whether or not negate the motor speed when either limit is reached.
For spring joints, there are 3 choices to set oscillation frequency:
- Presets: weak, normal or strong, the frequency will be calculated automatically.
- Custom Frequency (f): set the frequency directly
- Custom Spring Constant (k): set the spring constant k. 2π*f = sqrt (k/m).
- If you want to constrain all relative motions between the 2 shapes from start to finish in simulation, making them as brothers is more efficient than welding them with a weld joint.
- One byproduct effect of dummy joint is you can use the dummy joints as shape friend link by set its Collide Connected Shapes property false.
Using Utility and Preset Shapes
Using Bomb Component
Using Text and Text Button Components
Using Gravity Controller Component
Using Camera Component
You can make a camera and another shape as brothers, then in simulation, the camera will follow the another shape.
Using Power Source Components
Overview of The Trigger System
The core of the trigger system is Event Handlers. The trigger system provides the chances for designers to insert a code snippet to run when some events happen.
An event handler has one Code Snippet property. There is one specific tab panel for this property in the setting dialog.
All event handlers have two optional properties:
- Input Condition Entity: when an event handler is triggered, the condition will be evaluated firstly. The code snippet only be executed if the evaluation result is true. If the input condition is not assigned, the code snippet will be always executed.
- External Action Entity: after the code snippet is executed, the action will be also executed.
A action entity also has a code snippet property. Executing an action entity means executing the code snippet of the action entity.
There are 3 condition entity types:
- Basic Condition Entity. A basic ondition entity also has a code snippet property. Evaluating a basic condition entity means executing the code snippet of the condition entity and returning the boolean result.
- Condition Gate Entity. A condition gate can have multiple other condition entities as the input conditions and output a result of one of the following 4 gate operations: And, Nand, Or and Nor.
- Task Aggregator Entity. A task aggregator can have multiple Entity Selector properties. Currently, there is only one entity selector type: Entity Assigner (see below).
A condition will only be evaluated most once per step.
You can use an entity assigner to select some entities manually.
You can use an entity pair assigner to select some entity pairs manually.
Code Snippet Editing
Event handler, basic action and action entities all have a code snippet property. There is a code snippet tab panel specially for this property. You can make programming in this dialog panel.
For the available APIs, please read Core API Reference.
Using Trigger Components
All trigger components use the Place Creation Style to create.
Using Entity Assigner Component
Entity assigners are used to select some entities manually.
To select/remove an entity from the select list, select the entity assigner firstly, then drag a link from the small circle to the entity to be assigned/removed. You can also select all selected entities by select the command in the context menu of the small circle.
Using Entity Pair Assigner Component
Entity pair assigners are used to assign some entity pairs manually.
You can select entity pairing type in the context menu of the entity pair assigner:
- one to one,
- many to many,
- many to any,
- any to many,
- either in many,
- both in many,
To assign an entity pair, select the entity pair assigner firstly, then drag a link from the small circle(s) to the target entity.
Using Action Component
You can view an action as a function without any input and output parameters.
Using Task Aggregator Component
Each entity has a task property. The task property has 3 possible values: finished, failed and undetermined. As a condition, the evaluated result of the task aggregator has the same 3 possible value. If the task properties of all the entities selected by the entity selectors are finished, then the evaluated result of the task aggregator is also finished. If any the task property of any entity selected by the entity selectors are failed, then the evaluated result of the task aggregator is failed. Otherwise, the evaluated result of the task aggregator is undetermined.
Sometimes you want to know whether or not the task properties of a group entities are all finished. You can use an entity assigner to select the group entities and set the entity assigner as an input assigner.
A task aggregator can have variable amounts of input entity assigners as the input entity assigners.
To set an entity assigner as an input assigner, drag a link between the task aggregator and the outer circle band of the entity assigner.
Using Basic Condition Component
The evaluated result must be stored in the only output boolean parameter.
Using Condition Gate Component
You can select the gate operations of a condition gate in its context menu. There are 4 operation types:
How to add/remove an input condition of a condition gate (G1):
- to add a task aggregator as an input condition, drag a link between one of the three circles of the task aggregator and the light gray area of the condtion door.
- to add a basic condition as an input condition, dray a link between the green areas of the basic condition and the light gray area of the condtion door.
- to add another condition gate (G2) as an input condition, dray a link between the white areas of G2 and the light gray area of G1.
Using Event Handler Components
If the Enabled property is false, then an event handler will be trigger when the corresponding event happens. The Enabled property can be modified at runtime through programming.
To set a condition entity as the input condition, drag a link from the blue areas of the event handler to the condition entity.
To set an action entity as the external action, drag a link between the blue areas of the event handler to the red areas of the action entity.
Some entity specified event handlers can have multiple input Entity Selector properties. To set an entity assigner as an input entity selector, drag a link between the blue areas of the event handler to the outer circle band of the entity assigner.
Some entity pair specified event handlers have multiple Entity Pair Selector properties. To set an entity pair assigner as an input entity pair selector, drag a link between the blue areas of the event handler to the outer circle band of the entity pair assigner.
For some event handlers, there are some specific options in the basic tab setting panel:
- for a keyboard event handler, you can select which keys will trigger the keyboard events.
- for a timer event handler, you can set the timer interval and whether or not run once only.
For more, please read User Manual.