Fusion3 Blog - Collisions, Editors & Spatial Audio (Patreon)
Content
Our recent efforts in Fusion3 have focused on frame editor features and enhancements, and this time we've got three main things to show: a polygonal editor for objects you enable polygonal collisions for, a new object for displaying positional audio falloff in the frame editor, and a working implementation of the instance overview panel that we showed sketches of last time. Scroll to the headings below for more information on each new feature!
Collision Polygon Editor
The new Collision Polygon Editor lets you create a collision shape directly over an Object's image. Points can be placed and moved on the canvas, while exact coordinates remain available when needed. Instead of entering a list of numbers and hoping the result is correct, you can see the collision outline as it is built.
An Object can contain several polygon groups. This helps with Objects that have separate solid areas, such as vehicles, broken platforms, or scenery with large gaps. Each group has its own color and outline, making complex shapes a bit easier to read.
The editor can also create several common preset shapes, including rectangles, triangles, circles, capsules, and regular polygons. These shapes can then be moved, resized, rotated, and edited point by point. Selecting multiple points/groups at once is also possible, of course.
A capsule may be a useful starting point for a character. A rectangle can quickly cover a platform. A large Object with several separate parts can use more than one group without filling the empty space between them.
The editor checks every group while it is being changed. It can identify convex, concave, incomplete, invalid, and self-intersecting polygons. Crossed edges are shown in red, and warning messages explain what needs attention, making it possible to catch a bad shape before running the game. A polygon may look correct at first while still containing crossed edges, repeated points, or no usable collision area, so we make it obvious and easy to fix.
The Object's hot-spot can be changed from the same editor. Moving it keeps the polygon in the same visible place around the image. This is useful for Objects such as doors, wheels, rotating platforms, and swinging weapons, where the rotation point is an important part of the setup.
The polygon editor and the frame editor both behave similarly, supporting zooming, panning, grids, snapping, rulers, and more, so you don't have to re-learn different UI conventions.
The Element Tree control displays Groups, and Points associated to each Group in a tree-like fashion. Manual modifications, selections, and warnings can also be accessed there.
Triangulation
A polygon begins as an ordered outline, but the runtime doesn't test the complete outline as one large shape. It first divides the polygon into triangles, in a process naturally called triangulation.
Triangles are simple and reliable shapes for collision testing. They also make it possible to support concave polygons, such as an L-shaped platform or an Object with an inward corner.
Before creating the triangles, Fusion3 checks the polygon's points. Repeated points and unnecessary points along straight lines are optimized away, and then the shape is checked for crossed edges and for enough area to form a valid polygon.
Currently, valid polygons are split using an ear-clipping method. The system looks for a corner that forms a triangle inside the polygon without containing any of the remaining points. That triangle is removed from the working outline, and the process repeats until the full polygon has been divided.
If the previous statements don't make much sense to you: don't worry! Fusion3 is already doing it all internally and displaying the results directly on the canvas in realtime. Faint lines show the triangles inside each group, and the group header shows both its point count and triangle count. If you're particularly performance-minded, you can use these to judge runtime complexity, but most of the time you can ignore it.
Moving a point updates the triangle preview immediately, giving a realtime view of the data that will actually be used for collision testing, especially when working with concave shapes.
Triangulation also helps with reducing complexity for physics engines. One of the physics engines F3 supports is Box2D, which allows no more than eight vertices in a single polygon shape and expects that shape to be convex. Rather than pass the complete collision outline to Box2D as one polygon, each polygon group is instead divided into triangles, and each triangle becomes a separate Box2D shape attached to the same physics body. This allows one Object to use a detailed concave outline with far more than eight points, or to contain several disconnected polygon groups. Box2D's eight-vertex limit still applies to each individual shape, but every generated shape is only a three-point triangle.
There is no fixed point or group limit in the editor. The practical limit is performance, since more points produce more triangles, and more triangles mean more Box2D shapes and collision work. The same triangle data is also used by Fusion3's own collision tests. Polygon against polygon checks compare their triangles, while box, circle, and pixel-perfect collision tests use the triangle mesh when meeting a polygon.
If a group is incomplete, crosses itself, or can't produce valid triangles, it is marked as invalid instead of quietly creating broken collision data.
Collision System Changes
The runtime collision system has been expanded to support the new editor and a wider range of shapes. Objects can use an automatic shape, no collision shape, a box, a circle, a polygon, or a pixmap for pixel-perfect collisions.
These choices allow each Object's collision mask to be as detailed or as plain as it actually needs to be. A wall may only need a simple box collision mask, while a ball can use a circle. Sloped ground can use polygons, and a detailed sprite can use a pixel-perfect mask.
Different shape types can also be tested against each other. A circle can meet a polygon, a box can meet a pixel-perfect mask, and two polygon Objects can be checked using their triangle data.
This allows a project to mix collision types. A character may use a simple rounded shape while walking across detailed polygon ground. Projectiles may use small boxes, while a larger enemy uses several polygon groups.
Collision shapes follow the Object's position, size, scale, angle, and hot-spot. When the shape changes, movement and physics systems are notified so they can update their own data.
Sprites have gained some extra control too. A separate animation can be used as the source of the collision mask. The visible animation can remain detailed while a simpler hidden animation supplies more stable collision masks, generally one of the most highly requested features. Pixel-perfect masks can also be set to rotate with the Object or remain unrotated.
Collision layers provide another way to organize interactions. An Object can use its current Frame layer or refer to another named collision layer. This can help separate interface Objects from gameplay, represent different floors, or allow Objects drawn on separate layers to share the same collision space.
Frame Editor Improvements
Some Frames are easier to work on from another angle. Diagonal roads, sloped rooms, pinball tables, and isometric-style layouts can become awkward when the editor view is always upright.
The Frame Editor's view can now be rotated arbitrarily by holding Ctrl and dragging over empty space. An angle display appears during the movement so the current view angle remains clear. Only the editor view is rotated; the Objects keep their original positions and angles.
This allows a diagonal part of a level to be turned until it is easier to work with, without changing the Frame itself. Panning, scrolling, and zooming have also been updated to follow the rotated view.
The Frame Editor can also display polygon collision previews over selected Objects. This helps connect the shape created in the Polygon Editor with the Object as it appears in the Frame.
Additionally, finite Frames now display horizontal and vertical measuring lines showing the Frame's width & height along its top and left sides to better convey the size of the Frame area without having to check properties. This will be more useful once we add lines for the camera region as well, eliminating the age-old confusion over the difference between Frame Area size and Camera Region sizes.
Visual Changes
The editor has received a wider set of visual changes alongside the main features.
Certain controls like buttons, tabs, and panels can now react to the pointer's position. A soft highlight follows the pointer, while nearby borders become brighter. The effect fades when the pointer leaves.
For more substance, we also added subtle animating grain/noise. This gives previously very empty, flat, and lifeless areas more life and elegance/premium feeling. All of these effects can be configured or disabled.
Clicking some controls produces a small ring from the click position. Other controls use a slight press effect, where the clicked area moves inward while the opposite side stays in place. Some others are playful, like an iOS-shake effect when picking a group, or jelly-like physics as you drag it around.
The Properties panel has also received changes aimed at readability. Property rows now use subtle alternating background shades. This helps the eye follow a property name across to its value, especially in long lists where several rows use similar controls.
Property section headers take part in the same pattern, so the row colors continue through the full list. A divider between property names and values adds another guide without making the panel feel like a heavy table.
Most UI is resizable of course. Seen below is also a work-in-progress property editor for the object angle - F3 doesn't use the 32 directions system anymore but you can customize the angle editor to show the old values along the perimeter if you're coming from prior versions of Fusion.
The theme system controls these colors and effects. Pointer highlights, row shades, animation speed, grain strength, and other details can be changed without rewriting each control separately. We also plan to make a dedicated Skin Editor where you'll be able to configure these effects yourself.
Most of these changes are actually part of the Nucleus runtime, which means your own apps and games will be able to utilize the same effects that the F3 editor uses, if so desired.
We have lots to polish about the GUI and UX as stated in the previous blog, and are still prioritizing features and stability over fancy UI, so this is an early preview of what's to come.
Instance Overview Panel
As a Frame grows in complexity, it becomes difficult to see all the differences between objects from their visuals alone. Two Objects may look identical while using different values, one instance may be on the wrong layer, another may have a small angle or scale difference, an inherited Object may contain a local change that is not obvious from the Frame… it becomes easy to lose track.
The Instance Overview Panel (IOP) provides a table-like view of the current Frame. Instances (each visual object you see in the Frame editor) are grouped by Object type, with the Object's name and icon shown at the top of each section.
Each row represents one instance. Standard columns include position, layer, width, height, scale, and angle. Object-specific properties can appear as extra columns, so the information changes based on the selected Object type.
An enemy could show values such as health or speed, while a door could show its destination, and a collectible could show its type or value. Normal, inherited, and selected rows have different visual states, while changed values receive their own mark. This helps show which values came from a parent Frame and which were changed on a specific instance without filling the table with extra icons.
Rows can be sorted by one or more columns, columns can be resized, and large Object sections can be collapsed. Extra property columns can scroll sideways without moving the fixed instance information.
Selection remains connected to the Frame Editor. Selecting a row selects the matching Object in the Frame, making the overview another way to find Objects in a crowded scene. The panel does not replace the Properties panel, rather, it provides a wider view that is difficult to get from the canvas or from inspecting one Object at a time.
Jukebox and Spatial Audio
The final part of this update is the Jukebox, a placeable audio Object with spatial sound controls.
We're putting a lot of thought into making cross-platform audio simple and powerful. The Nucleus runtime has rudimentary audio handling currently while we experiment with how best to surface the audio capabilities of every platform. For now, we've begun experimenting with how to represent positional audio in the Frame editor.
Introducing the Jukebox object: Insert it into the Frame, pick or import audio, adjust the range from the visual handles and listener position by moving the connected ear, and voila! Right away, you get working surround audio!
A Jukebox can use any supported audio resource you add to your project. It supports all the same playback controls that normal sound channels do. It can use normal mono output with left and right panning, or position-based surround output. Currently, simulating the doppler effect (speed of sound delay) is not implemented, but we're working on it!
In surround mode, the Jukebox has a sound-source position and a listener position. The direction between them is used to spread the sound across the available speakers, including surround sound speaker setups in addition to typical stereo and headphones.
This can be used for a waterfall, moving vehicle, alarm, machine, fire, or another sound that belongs to a place in the Frame. Of course, everything can move at runtime, but the Jukebox object is intended to be useful for working in the Frame editor, where objects don't move unless you move them.
The sound has an inner and outer range. Inside the inner range, it uses the chosen maximum range volume. Between the two ranges, the volume levels are interpolated gradually. At and beyond the outer range, the minimum value is used. The minimum is typically silence, but it doesn't have to be - a large waterfall could remain faintly audible across the whole Frame area and become much louder as the listener approaches, for example.
These ranges are shown in the Frame Editor as circles around the source. The source, listener, and range handles can be adjusted visually, while optional rings show how the volume changes across the area.
Just like with normal sound channels, all Jukebox settings and playback can be controlled through Events while the game is running. That includes Actions for changing behavior, Conditions for detecting when playback finishes, or querying values such as playback progress, duration, listener distance, and current range volume via Expressions.
(Icons and menu layout are WIP and will be changed drastically.)
Preview options are exposed like the range's color palette and ability to hide the volume indicators, making it easier to distinguish an audio Object in the Frame. As a debugging feature, we plan to allow showing the same display at runtime as well.
Jukebox marks the point where Audio in Fusion becomes Object-oriented, rather than the more "singleton"-fashion of F2.5's System Sound Object. In addition to allowing for positional audio, easy attachments, and more natural interaction, it also allows for grouping/tagging, flexible filtering, and eliminating channel confusion. All of this comes naturally from switching over to an OO model. In previous blogs we also mentioned that objects can contain other objects, so you can also put these Jukebox objects inside of other objects to group them together and move and rotate them as one.
As mentioned, the Jukebox object is experimental - we request your thoughts and feedback on how else we can improve the audio development experience within Fusion.
Summary
These features began in different parts of Fusion3, but they solve a similar problem: important information should be visible while working on a project, and it should be visualized in a natural intuitive way.
Collision polygons can be drawn, checked, and triangulated in the editor before being used by the runtime and Box2D. Frame rotation makes some layouts easier to work with, while the visual changes improve feedback and readability across the editor.
The Instance Overview Panel exposes differences that are difficult to see on the canvas. The Jukebox does the same for sound by showing its source, listener, and range directly in the Frame editor.
Together, these changes make several parts of a project easier to inspect and adjust without hiding as much information behind raw values or runtime testing. There is still work to do, but we hope that it's a solid start on what's to come!