CryENGINE 3: Sandbox Basics tutorial

In this article by Dan Tracy, author of CryENGINE 3 Cookbook, we will cover:

• Placing the objects in the world
• Refining the object placement
• Utilizing the layers for multiple developer collaboration
• Switching to game mode
• Saving your level
• Exporting to an engine
• Essential game objects
• Running a map from the Launcher

Placing the objects in the world

Placing objects is a simple task; however, basic terrain snapping is not explained to most new developers. It is common to ask why, when dragging and dropping an object into the world, they cannot see the object. This section will teach you the easiest ways to place an object into your map by using the Follow Terrain method.

Getting ready

1. Have My_Level open inside of Sandbox (after completing either of the Terrain sculpting or Generating a procedural terrain recipes).
2. Review the Navigating a level with the Sandbox Camera recipe to get familiar with the Perspective View.
3. Have the Rollup Bar open and ready.
4. Make sure you have the EditMode ToolBar open (right-click the top main ToolBar and tick EditMode ToolBar).

How to do it...

First select the Follow Terrain button. Then open the Objects tab within the Rollup Bar. Now from the Brushes browser, select any object you wish to place down (for example, defaults/box).
You may either double-click the object, or drag-and-drop it onto the Perspective View. Move your mouse anywhere where there is visible terrain and then click once more to confirm the position you wish to place it in.

How it works...

The Follow Terrain tool is a simple tool that allows the pivot of the object to match the exact height of the terrain in that location. This is best seen on objects that have a pivot point close to or near the bottom of them.

There's more...

You can also follow terrain and snap to objects. This method is very similar to the Follow Terrain method, except that this also includes objects when placing or moving your selected object.
This method does not work on non-physicalized objects.

Refining the object placement
After placing the objects in the world with just the Follow Terrain or Snapping to Objects, you might find that you will need to adjust the position, rotation, or scale of the object. In this recipe, we will show you the basics of how you might be able to do so along with a few hotkey shortcuts to make this process a little faster. This works with any object that is placed in your level, from Entities to Solids.

Getting ready

1. Have My_Level open inside of Sandbox
2. Review the Navigating a level with the Sandbox Camera recipe to get familiar with the Perspective View.
3. Make sure you have the EditMode ToolBar open (right-click on the top main ToolBar and tick EditMode ToolBar).
4. Place any object in the world.

How to do it...

In this recipe, we will call your object (the one whose location you wish to refine) Box for ease of reference.

1. Select Box.
2. After selecting Box, you should see a three axis widget on it, which represents each axis in 3D space. By default, these axes align to the world:
   • Y = Forward
   • X = Right
   • Z = Up

To move the Box in the world space and change its position, proceed with the following steps:

1. Click on the Select and Move icon in the EditMode ToolBar (1 for the keyboard shortcut).
2. Click on the X arrow and drag your mouse up and down relative to the arrow's direction.
3. Releasing the mouse button will confirm the location change.

You may move objects either on a single axis, or two at once by clicking and dragging on the plane that is adjacent to any two axes: X + Y, X + Z, or Y + Z. To rotate an object, do the following:

1. Select Box (if you haven't done so already).
2. Click on the Select and Rotate icon in the EditMode ToolBar (2 for the keyboard shortcut).
3. Click on the Z arrow (it now has a sphere at the end of it) and drag your mouse from side to side to roll the object relative to the axis.
4. Releasing the mouse button will confirm the rotation change.

You cannot rotate an object along multiple axes. To scale an object, do the following:

1. Select Box (if you haven't done so already).
2. Click on the Select and Scale icon in the EditMode ToolBar (3 for the keyboard shortcut).
3. Click on the CENTER box and drag your mouse up and down to scale on all three axes at once.
4. Releasing the mouse button will confirm the scale change.

It is possible to scale on just one axis or two axes; however, this is highly discouraged as Non-Uniform Scaling will result in broken physical meshes for that object. If you require an object to be scaled up, we recommend you only scale uniformly on all three axes!

There's more...

Here are some additional ways to manipulate objects within the world.

Local position and rotation

To make position or rotation refinement a bit easier, you might want to try changing how the widget will position or rotate your object by changing it to align itself relative to the object's pivot. To do this, there is a drop-down menu in the EditMode ToolBar that will have the option to select Local. This is called Local Direction. This setup might help to position your object after you have rotated it.

Grid and angle snaps

To aid in positioning of non-organic objects, such as buildings or roads, you may wish to turn on the Snap to Grid option. Turning this feature on will allow you to move the object on a grid (currently relative to its location). To change the grid spacing, click the drop-down arrow next to the number to change the spacing (grid spacing is in meters). Angle Snaps is found immediately to the right of the Grid Snaps. Turning this feature on will allow you to rotate an object by every five degrees.

Ctrl + Shift + Click

Even though it is a Hotkey, to many developers this hotkey is extremely handy for initial placement of objects. It allows you to move the object quickly to any point on any physical surface relative to your Perspective View.

Utilizing the layers for multiple developer collaboration
A common question that is usually asked about the CryENGINE is how does one developer work on the same level as another at the same time. The answer is—Layers. In this recipe, we will show you how you may be able to utilize the layer system for not only your own organization, but to set up external layers for other developers to work on in parallel.

Getting ready

1. Have My_Level open inside of Sandbox.
2. Review the Navigating a level with the Sandbox Camera to get familiar with the Perspective View.
3. Have the Rollup Bar open and ready.
4. Review the Placing the objects in the world (place at least two objects) recipe.

How to do it...

1. For this recipe, we will assume that you have your own repository for your project or some means to send your work to others in your team.
2. First, start by placing down two objects on the map. For the sake of the recipe, we shall refer to them as Box1 and Box2. After you've placed both boxes, open the Rollup Bar and bring up the Layers tab.
3. Create a new layer by clicking the New Layer button (paper with a + symbol).
4. A New Layerdialog box will appear. Give it the following parameters:
   • Name = ActionBubble_01
   • Visible = True
   • External = True
   • Frozen = False
   • Export To Game = True
5. Now select Box1 and open the Objects tab within the Rollup Bar.
6. From here you will see in the main rollup of this object with values such as – Name, Helper Size, MTL, and Minimal Spec. But also in this rollup you will see a button for layers (it should be labelled as Main). Clicking on that button will show you a list of all other available layers.
7. Clicking again on another layer that is not highlighted will move this object to that layer (do this now by clicking on ActionBubble_01).
8. Now save your level by clicking—File | Save.

Now in your build folder, go to the following location: -... \Game\Levels\My_Level. From here you will notice a new folder called Layers. Inside that folder, you will see ActionBubble_01.lyr.

This layer shall be the layer that your other developers will work on. In order for them to be able to do so, you must first commit My_Level.cry and the Layers folder to your repository (it is easiest to commit the entire folder).

After doing so, you may now have your other developer make changes to that layer by moving Box1 to another location. Then have them save the map.

Have them commit only the ActionBubble_01.lyr to the repository. Once you have retrieved it from the updated repository, you will notice that Box1 will have moved after you have re-opened My_Level.cry in the Editor with the latest layer.

How it works...

External layers are the key to this whole process. Once a .cry file has been saved to reference an external layer, it will access the data inside of those layers upon loading the level in Sandbox.
It is good practice to assign a Map owner who will take care of the .cry file. As this is the master file, only one person should be in charge of maintaining it by creating new layers if necessary.

There's more...

Here is a list of limitations of what external layers cannot hold.

External layer limitations

Even though any entity/object you place in your level can be placed into external layers, it is important to note that there are some items that cannot be placed inside of these layers. Here is a list of the common items that are solely owned by the .cry file:

• Terrain
  • Heightmap
  • Unit Size
  • Max Terrain Height
  • Holes
  • Textures
• Vegetation
• Environment Settings (unless forced through Game Logic)
  • Ocean Height
• Time of Day Settings (unless forced through Game Logic)
• Baked AI Markup (The owner of the .cry file must regenerate AI if new markup is created on external layers)
• Minimap Markers

Switching to game mode
CryENGINE prides itself on the saying What you see is what you play, and the switching to game mode is a testament to this.

It goes without saying that testing your work often is the key to a successful project, and the quick easy use of switching to Game Mode within the Editor allows you to test at will without the need to close Sandbox.

Even though the Editor is built with this feature to allow Developers to check their work, this is still only an emulation. This means that there are several special editor rules and debug options available in this mode, which isn't fully representative of what the Player might see in the Pure Game. Even though it is an excellent idea to test often by switching to Game Mode, it is also important to do any final testing in the Launcher on your target platform to have a proper Pure Game experience.

In this recipe, we will cover the simple, but highly important use of switching to game mode. This function allows you to jump into your level instantly, and allows you to test what the player will see, hear, and feel within the location you are at with your Perspective Camera.

Getting ready

Have My_Level open inside of Sandbox. Review the Navigating a level with the Sandbox Camera to get familiar with the Perspective View.

How to do it...

In the Sandbox main toolbar, find Game | Switch to Game or click on Ctrl + G. It's that simple.
Game Logic can change the player's initial spawning location. If this logic is enabled, then you will be forced to spawn at this location as well when entering game mode.

Saving your level
On the surface, saving your level seems like a simple process; however, there are a few important functionalities that you should be aware of when saving your level. This recipe will show you how to do a basic saving, copying/moving your level (do not use Save As), and auto backups.

Getting ready

Have any level open inside Sandbox. Open Windows Explorer to the following location: ...\CryENGINE_Build\Game\Levels.

How to do it...

To save a level, go to File | Save.
Ctrl + S does not work by default. You will need to set up a shortcut key yourself for that.
When copying/moving levels:

1. Initially, save your level to its default location.
2. Go to the level's location in Windows Explorer (…\Game\Levels).
3. Using Windows commands copy/cut the entire My_Level folder.
4. Paste the level into the location you want.
5. If necessary, rename both the My_Level folder and My_Level.cry to something you prefer.

We recommend that you never perform a Save As for your level. Unfortunately, there are several dependencies (Level.pak, TerrainTexture.pak, Layers, Minimap images, and so on) that do not get moved or relink themselves when a Save As is performed. They are all dependent on the folder in which they are placed. If you do this, you will see several anomalies within your level (broken textures, bugs in game logic, missing assets).

When creating a backup, remember that by default, Sandbox creates My_Level.bak files after the second/third time your level is saved. These .bak files are essentially the previous saves of your .cry file.
If, for whatever reason, you need to revert back to a previous save of your level, you may delete your My_Level.cry file and rename My_Level.bak# to My_Level.cry and reopen your level inside of Sandbox.
Also, by default, Sandbox creates up to two previous revisions (My_Level.bak and My_Level.bak2).

How it works...

By default, all levels are saved in their own folder inside of ...\Game\Levels by their level name. For example, My_Level will have its own folder with the level's folder. Once saved, each level will also contain a *.cry file, with the * being the name of the level as well. Each of these .cry files hold all the relevant information that is required to make up your level (much like a blueprint for your level).

There's more...

Depending on your work style, you might want to enable the Auto Backup system. This will automatically save your work every X minute interval with the name of your choice (Autobackup by default) into your level's folder. These Auto Backups will save continuously as long as your editor is open or you turn this feature off.

To access this feature, open Sandbox | Tools | Preferences | General/Files | Auto Backup.

Exporting to an engine
Even though saving your level will create a .cry file for you, it is extremely important to note that a .cry alone will not work in the Launcher. For that you will need to perform this recipe, which will create the required files to run in Pure Gamemode.

Getting ready

Have My_Level open inside Sandbox.

How to do it...

Go to File | Export to Engine or click on Ctrl + E.

How it works...

This crucial step is required to convert all the blueprint's setup in your .cry file in to a level.pak inside of the My_Level folder to be used in Pure Gamemode. This level.pak is basically a cache of data for the game to use, which houses all the baked information about Game Logic, AI Markup, Particle list, Brush list, and so on.

There's more...

Here is some useful information that you should know about .pak files.

Opening .pak files

It is possible to open these .pak files and see the information stored inside them by using third-party compression software, such as WinZIP and WinRAR. However, we do not recommend doing this unless you are familiar with handling the files you may wish to manually change. If you do change the files that are inside of these .pak files, you run the risk of damaging the .pak file and breaking your level for the Launcher.

Corrupted .pak files should be deleted and re-exported

There is no need to panic if, for whatever reason, any of your .pak files become corrupted and unusable in Pure Gamemode. You can always delete them and generate a new one from your My_Level.cry by repeating this recipe.

Essential game objects
Even though we covered how to export your level to be used in Pure Gamemode, you may find that when you launch your level, you are not in the correct location in the map. This quick recipe will show you how to create a Spawn point for Pure Gamemode and also remind you the importance of having a physical surface to spawn on.

Getting ready

1. Have My_Level open inside of Sandbox.
2. Review the Navigating a level with the Sandbox Camera to get familiar with the Perspective View.
3. Review the Placing the objects in the world and Refining object placement recipes.
4. Have the Rollup Bar available in your Sandbox layout and ready.

How to do it...

Unless your game supports some sort of Player flying mechanic, we recommend you choose a location where the Player can stand when he initially spawns within your level. Any physical surface (Floor, Roof, Terrain, Rock, and so on) will do.
To place a Spawn Point follow these steps:

1. Go to your Rollup Bar.
2. Open the Objects tab and click the Entity button.
3. Open the Others folder in the Entity List.
4. Place Spawn Point in the location you wish to spawn the player.

How it works...

This initial spawn point will automatically work as the main spawn point for your map in Pure Gamemode (as long as you keep to the default SinglePlayer.lua gamerules). If you jump into your map from the Launcher now, you will be spawned at this location.

Any additional spawn points will not function unless there is some game logic hooked into their functionality.

Running a map from the Launcher
The final recipe in this article will cover how you may access the Pure Gamemode version of My_Level from the Launcher.

Getting ready

You must have a map with a working spawn point (otherwise you will spawn at 0,0,0), that has been exported from the engine with a functional level.pak.
The level must also be inside your Build folder.

How to do it...

1. From Windows Explorer, open either ...\Bin32 or ...\Bin64.
2. Launch the executable Launcher.exe.
3. Open the console (~).
4. Type the following: map My_level.
5. Then press Enter.

This will load the map as well as spawn you in the spawn point that was provided.

Over 90 recipes written by Crytek developers for creating third-generation real-ti