Voxel Object Editor

Where should I position my object on the grid?

The pivot, or position the object will rotate around and be positioned at in a game is always at the middle position of the Voxel Object Editor this is position by the cross on the build plane in the editor, shown below.

When building an object it’s good practice to place the most likely part of the object you’d want to position or rotate it in that spot. For example a bunch of flowers designed to be held might want the pivot to be at the position it will be attached to the player's hand.

You should also consider the direction your object faces when building it. For example the same bunch of flowers probably wants to be built vertically. But a car might want the body to be facing forwards. The arrow on the build plane shows which direction forwards is.

How can I rotate just part of my object? (explain how to do it in another frame for now)

One way you can do this:

• Select what you want to have rotated.
• Pull it to one side with the translate handles.
• Rotate the object by using the rotate buttons.
• Select what you want rotated and press Ctrl-C to copy it.
• Undo the rotation.
• Paste the rotated piece back in with Ctrl-V, select it and pull it back into place with the translate handles
• Make sure to delete the unwanted unrotated piece.

Another way is to:

• Open a new frame of animation with the “+” button at the bottom.
• In that new frame, make your rotation, select and copy the rotated piece you want.
• Delete that frame with the “x” button at the bottom.
• Paste the rotated selection into the original frame.

What if I need my edit plane in a different location/orientation?

These shortcuts will help you adjust the work plane:

• Alt+R - To rotate the work plane
• Alt+Up - To move the work pane up
• Alt+Down - To move the work plane down

How do I copy colors between voxel objects?

You can copy colors from one object to another by:

• Opening both objects in two separate tabs.
• In the tab of the object you want to copy the color from:
  • Mouse over the color and press space.
  • Open the color wheel at the top of the tools bar.
  • Select the text in the bottom-right corner of the color wheel and copy it.
• In the tab of the object you want to use the color:
  • Open the color wheel.
  • Paste the text you copied previously into the same spot, overwriting what's there and press enter.
  • You can now color voxels with that color.

It’s useful to build up a little palette to one side of the object you’re building so you can quickly copy all of the colors you want over and use it to help you when painting your object. You can also save your palette as its own object to keep remixing objects from, if you have a set of palettes you prefer to use frequently!

How do I fill only a certain chunk of voxels with a color?

With the selection tool, you can double click to select all connected voxels of that color. CTRL+Shift+double click can grab every use of that color. With a selection active, the bucket fill tool will only fill or color replace what’s selected.

Game Editor

How do I make a new player template?

In your game with the game running:

• Make sure you’re in ‘Advanced’ mode in the bottom bar selector.
• Select the player entity.
• Open the Entity section of the inspector.
  • Under the Template section click ‘Unlink from Template’.
  • Click ‘New Template’.
  • Rename your template to something sensible.
  • Click ‘Save’.
• In the Save Options under Additional Game Options:
  • Click the Player Template reference box.
  • Browse to your new template and double click it.
  • Save the game.
• Stop the game and start it and it will be using the new player template which you can continue to edit and update.

How do I delete my player template entity from the game after I’m done editing it?

The editor wants to make sure you don’t accidentally delete your player entity while playing, so you need to remove the ‘player’ tag from the template entity to remove it:

• Select the template Entity.
• Save your changes to the template.
• Remove the ‘player’ tag.
• Delete the Entity as normal.
• Note: You can also remove the “player” tag from your template, as it is added automatically by the engine if the entity is spawned as the default player Entity on startup.

How do I find templates made by other people?

Right now you can’t access templates made by other people directly. A work around is to have them place a copy of the template into your game and then create a new template from it.

Can I change the color of voxel objects in the game editor?

Right now you cannot programmatically change the color of voxels in a voxel object. However if you make your voxel objects in grayscale colors you can tint them using the emissive parameters of the Voxel Object component.

Can an entity have more than one voxel object assigned to it?

Yes, with some caveats. Our collision system when set to use Voxel Object collision will only consider the first Voxel Object. It will also only auto-fit the other shapes to the size of the first Voxel Object.

How does parenting work?

Parenting works by setting the Parent Entity reference in the Transform section of the inspector for an Entity to the Entity that should be its parent. This can also be assigned through our scripting API. This will fail if the parent entity is scaled non-linearly, which means one or more of the scale dimensions differs from the others (e.g. scale is like 0.5, 1, 3).

When an Entity is parented to another it inherits its parents position, rotation and scale and its own local position, rotation and scale will be added on top of that. This can be very useful to move groups of entities that should always be together around by just moving the parent. It can also be useful to create more complex animating entities, for example a turret that pivots on a base horizontally and pivots vertically on a spindle, each section would be a separate entity parented to the one below.

How do I make a template and when should I use one?

Templates let you save the setup of an entity, the components on it and all their properties and share it between multiple games. They're a very handy way to spawn in copies of the same entity, for example if you were making a firework launcher you would spawn the firework template or selection of firework templates from the launcher when it was fired.

You can create a template by:

• Selecting the entity you want to make a template from.
• In the Entity section of the Inspector.
  • Make sure you've named the Entity something sensible as this will be used when it's spawned.
  • Click the New Template template button.
  • In the box just above name your new template something sensible.
  • Click the Save button.

Your template will now be accessible to you in the 'Mine' section of the Templates tab in the Resource Browser at the bottom of the screen. You can also assign it to any template references you have in script properties.

Can objects only be scaled uniformly?

Yes. There are many long and boring reasons why but this restriction is there to prevent some very unintuitive behavior that can result. We are actively looking at ways to allow you to non-uniformly scale constituent parts of entities that will avoid these pitfalls.

Can I parent to objects that aren’t scaled uniformly?

No. Our current implementation causes children to inherit the scale of their parents. With rotation this results in skewing occurring which is almost never what you want. To avoid this we simply don’t allow parenting to non-uniformly scaled Entities. Thankfully this is hard to achieve as we also don’t let you scale entities non-uniformly but you might run across games or templates we’ve made that use non-uniform scaling.

Why can’t I walk through my door/gateway/up to my tree?

Most likely you are using Voxel Object collision and the collision system has determined that your object is too dense to use Voxel Object collision and has fallen back to box collision. You can decrease the density of your object by scaling it up in game or reducing the number of voxels it uses in the Voxel Object editor.

You can also create proxy collision geometry by using some other entities to represent it with our collision primitives. For example using box collision to frame the doorway with several entities and turning off collision on the visual entity.

How do I find lost entities in my game?

We have a very powerful Entity Search Panel that can be accessed in the top right corner of the editor.

It will search across Entities by name, tags and attached scripts. You can filter the search more precisely by toggling these options on and off as well as finding entities with specific kinds of components.

We highly recommend naming the items you add to the game, and template appropriately so you can find them easily with a search. It can also be very useful to tag groups of related entities (e.g. the entities that make up a house) so that you can easily find them.

How do I stop from selecting my environment?

We are in the process of providing a fully featured Entity Locking system to the editor but in the meantime entities that are named ‘Ground’ are not selectable in the editor.

Can I snap things to a grid?

If you hold down shift whilst moving or rotating an Entity it will snap in small steps. Starting entities at the same location will allow you to place them on the same grid relative to one another. In the future we’ll provide a more fully featured grid system.

Can I position things more precisely?

If you switch to Advanced mode as well as our universal transform widget you also get access to the standard translate, rotate and scale widgets. For extreme precision you can also input values directly into the Transform section of the Entity inspector.

What is the difference between basic and advanced mode?

Basic mode simplifies the editor interface a lot so it’s less intimidating if you’ve not used a 3D or game editor before. It also hides a bunch of unexplained or sometimes unintuitive options from you. If you’re confident in making games or hit a wall you can’t seem to get passed switching to Advanced mode is probably the right thing to do.

How many entities can I have in my game?

Games on dot big bang can be played on many devices and quite a few of those can be relatively low powered. To maintain reasonable performance we tend to limit ourselves to fewer than 1000 entities in a game when it is running as a rule of thumb.

Actual performance depends on what your game is doing and what work your scripts are doing. It’s important to test your game on a variety of devices you expect people to be playing with.

How can I check my game’s performance?

You can press F9 in game to get a stats panel that shows you a wide range of information about your games performance. For most games you want to start by looking at the update rate. This will depend on your screen's refresh rate as the browser will try to update the game to match it. We recommend you work hard to keep the game running at or above 60hz to give an optimal experience to players.

How many players can I have in my game?

The current limit is 24 players in a single instance but there is no limit on the number of active instances. They will be created, filled and removed as your players enter and leave the game. This limit is actually configurable but not exposed to normal users at the moment. If your game needs a lower player limit to make sense feel free to ask for help in Discord.

Why can’t I stop/start the game while multiplayer editing?

Only the game's host can stop and start the game whilst in multiplayer mode.

Why aren’t my changes saved while multiplayer editing?

Only the game's host can save the game whilst in multiplayer mode.

Scripting

Can I run some code when a new player joins a multiplayer game?

We’re working on revamping our game lifecycle callbacks to include this sort of functionality but in the meantime you can use the fact a player template will be spawned for each player that joins to add this yourself. The snippet of code below can be placed in start and sends an event to all entities with the “player**listener” tag. This means it will call the onPlayerJoined method on any scripts on those entities and pass through the new player entity as the first parameter.

start () {
    if (!this.entity.isOwnedLocally) {
            this.game.sendEventToTag(“player_listener”, “onPlayerJoined”, this.entity);
    }
}

Can I make sure a player that joins late gets the right state from my game?

When a player joins the game the current state of all the public properties of game entities are sent to them. That makes these properties the ideal place to keep state you want to be transmitted to joining clients. For more complex state you can implement the pattern above to detect a new player joining and use the sendMessage functionality that is part of our networking API to transmit new state.

What is Server Transfer and how do I make sure my game is compatible with it?

One peer is nominated as the ‘server peer’; this role has some limited responsibilities but doesn’t have to be authoritative (but can be) over the game state as you might expect in a traditional client-server implemented game. A server transfer occurs when the peer that has been elected to run the game leaves and a new peer is elected to take over. This can happen at any time and unfortunately a leaving peer does not necessarily exit cleanly so it’s not an event that can be responded to.

For a game to be compatible with server transfer it needs each peer to have enough state locally that it can take over running the game. This can be achieved by running the server logic in parallel without taking action, transmitting the state that peers will need to take over or inferring the current state from the information the peer has locally already. Usually a combination of all three is used depending on the specific gameplay mechanic. A drastic example of this could be ending the current game round when server transfer occurs allowing a clean slate game to be setup by the newly elected peer.

One way to avoid this issue entirely is to design the game to operate in a purely peer-peer manner where game state and rules are distributed amongst the peers such that one leaving does not break the game.

How can I run some code once a newly spawned entity has been completely set up?

We’re working on revamping our game lifecycle callbacks to include this sort of functionality but in the meantime you can simply wait until the first tick is run on the Entity. The snippet below shows one approach.

private _initialized = false;

tick () {
    if (!this._initialized) {
        this._initialized = true;
        // do your setup here knowing all the scripts on the entity have run start
    }
}

This has a slight performance penalty as tick will be run every frame even if it’s to do no actual work which might be an issue if you have lots of entities following this pattern. It’s preferable in that case to use event’s to structure your game initialization so that you have control of the ordering.

In general it’s worthwhile trying as far as possible to structure your code so that the ordering like this doesn’t matter.

Why are my contact normals coming out strange and what should I do about it?

As with all systems some bugs linger in our collision system. We’ve found that using the correctionVector that is also provided is often superior to the contactNormal. All you need to do is normalize it before use.

What is the difference between isNetworked and isTransformNetworked?

We offer two modes of networking.

isNetworked simply states that the entity will participate in networking, so will have a stable identity across peers in the instance and can send messages to and fro.

isTransformNetworked then includes the above and our batteries included networking of the entity transform and skeletal animation. This provides built-in interpolation on the non-owning peers as they receive transform updates so the entity motion remains smooth.

Can I keep things in sync without sending messages?

By default we keep a timer in sync between all the peers, this is called server time. The ‘server’ peer for an instance has the responsibility of tracking time and sending this to peers connected to the instance. This is periodically synced and between syncs other peers will continue to run the timer forward as normal. Using server time you can keep any time driven activity in sync by using the specific server time timer. This can be accessed by this.game.session.serverTime and is expressed in seconds since the instance was started.