Room 3D Manual · Guidry Games

Getting started

Room 3D builds 3D rooms for GameMaker, which has no 3D room editor of its own.

Add > Model from File… (Cmd/Ctrl+I, or the cube button in the toolbar): pick one or more model files. They appear in the Library at the bottom left. Or Add > Premade Character (C) for a ready-rigged character.
Double-click a model in the Library (or select it and press Enter) to put a copy in the room.
Click a thing in the room (or in the Outliner) to select it. Move it, turn it, pick its animation in the Inspector on the right.
Save to GameMaker (the gold button, Cmd/Ctrl+E) writes the room, the models and their animations into a GameMaker project.
File > Save Project (Cmd/Ctrl+S) keeps the work in a project file, to open again later.

Everything you do to the room can be undone (Cmd/Ctrl+Z). See The window for where everything is.

The window

The menu bar (on a Mac, the system's menu bar at the top of the screen; elsewhere, at the top of the window): every command, with its shortcut. See Menus.
The toolbar: Open and Save; Undo and Redo; the tools (Select, Move, Turn, Scale); Snap, Grid and Collision shapes; Add character and Add model; the Animation library and Combine animations; Help; and on the right Save to GameMaker. Rest the mouse on a button for its name and shortcut. A lit (gold) button is on.
Outliner (top left): what's in the room. See Outliner.
Library (bottom left): the open models, as pictures. See Library.
The view (middle): the room in 3D, with buttons at its top right for the views, lighting and what's shown, and the view's name at its top left. See The view.
Timeline (under the view): play the selected thing's animation. See Animations.
Inspector (right): the selected thing's settings, in sections that fold. See Inspector.
The status bar (bottom): the tool and what it does, what just happened, whether snapping is on, whether there are unsaved changes, and the project's name.

Drag the gaps between the panels to resize them. View > Show Panels (Cmd/Ctrl+1 to 4) hides or shows the Outliner, the Library, the Inspector and the Timeline. The sizes, hidden panels and folded sections are kept for next time; Window > Reset Panel Layout (Cmd/Ctrl+Alt+0) puts them back.

Menus

File: New Project (Cmd/Ctrl+N), Open Project… (Cmd/Ctrl+O), Open Recent, Save Project (Cmd/Ctrl+S), Save Project As… (Shift+Cmd/Ctrl+S), Save As and Collect Model Files… (Alt+Cmd/Ctrl+S), Close Project (Cmd/Ctrl+W), and Quit (on a Mac in the Room 3D menu, Cmd+Q).
Edit: Undo, Redo, Duplicate (Cmd/Ctrl+D), Delete (Delete / Backspace), Rename… (F2), Deselect (Esc), the tools (Q, W, E, R), Snap (S), Fit Collision Shape (Shift+K), Next Collision Shape (Alt+K), Preferences… (Cmd/Ctrl+,).
View: Front (1), Side (3), Top (7), Perspective (5), Frame Selected (F), Frame All (Shift+F), Grid (G), Collision Shapes (K), Lighting (Shift+L), Show Panels.
Add: Premade Character (C opens it with pictures), Model from File… (Cmd/Ctrl+I), Selected Library Model (Enter), Remove Model from Library.
Animation: Animation Library… (Cmd/Ctrl+L), Combine Animations… (Shift+Cmd/Ctrl+L), Events… (M), Attach to Bone… (P), Detach (Shift+P), Play / Pause (Space), Go to Start (Home), Loop (L).
Export: Save to GameMaker… (Cmd/Ctrl+E), Save Model to GameMaker… (Shift+Cmd/Ctrl+E), Save Model as GLB… (Alt+Cmd/Ctrl+E).
Window: Welcome Window (Shift+Cmd/Ctrl+H), the Animation library, Combine and Help windows, Reset Panel Layout, Full Screen.
Help: Room 3D Help (F1), Room 3D Manual (Web) (Shift+F1), Keyboard Shortcuts (Cmd/Ctrl+/), Release Notes; Sign In… (or Account), Licence…, Enter Licence Key…, Buy Room 3D…; Check for Updates…, Report a Problem…, guidrygames.com; About Room 3D. See Help and support.
The Room 3D menu (on a Mac, the app's own menu): About Room 3D, Check for Updates…, Sign In…, Licence…, Preferences…, and Quit (Cmd+Q).

Items that need a selected thing are greyed out until one is selected. Ticks show what's on (the tool, Snap, Grid…). Keys without Cmd/Ctrl work wherever you are except while typing in a box; Cmd/Ctrl keys work everywhere (in a box, Cmd/Ctrl+Z undoes the typing).

Welcome window

Shown when Room 3D starts (unless it was started with a project or a command-line option):

New Project, Open Project…, Open Model… and Help.
Recent projects: click one to open it (greyed out if its file has gone).
Start with a premade character: a new room with that character in it.
Don't show at launch: start with an empty room instead. Window > Welcome Window (Shift+Cmd/Ctrl+H) shows it any time, and Preferences can turn it back on.

Outliner

The list of things in the room (top left).

Click a thing to select it (the same as clicking it in the view). Click empty space to select nothing.
Double-click (or F2, or the pencil button) to rename it. Names are unique in the room and are made valid GameMaker names; things attached to it follow the new name. Renaming can be undone.
Each thing's icon says what it is: a person for a character (a model with a skeleton), a film for a model whose parts move, a cube for a still model.
Something attached to a bone sits under what carries it, with the bone's name beside it.
Drag a thing onto another to attach it to one of that one's bones: the Attach to bone window opens with it chosen. Drag an attached thing onto empty space to detach it.
The bin button (or Delete) takes the selected thing out of the room.

Library

The open models (bottom left), each with a picture: a premade character's own, or the model drawn from three-quarters.

Double-click a model (or select it and press Enter) to put another copy in the room.
The buttons at the top: a premade character (C), a model from a file (Cmd/Ctrl+I), and remove the selected model (the bin, or Delete in the Library); if copies of it are in the room, it asks first and removes them too.
Rest the mouse on a model for its file, its animations and the size it's shown at.

Inspector

The selected thing's settings (right). At the top: its name, what it is and its model. Each section folds (click its title); folded sections stay folded next time.

Transform: Position (x, y up, z, in metres), Turn (degrees about x, y and z) and Scale (1 is as made). Type a number, or use the arrows. Typing in a box is one undo step.
Animation: the Clip it plays, Loop, Events… and the Animation Library….
Collision: its collision shape for GameMaker (see Collision shapes).
Attach to bone: what it follows, Attach to Bone… and Detach.
GameMaker: its Name (its thing_name; Enter renames) and the Object it becomes in GameMaker (made for you if the project hasn't got it).

With nothing selected, the Inspector says how many things are in the room.

Preferences

Edit > Preferences… (Cmd/Ctrl+,; on a Mac also in the Room 3D menu as Settings):

Show the Welcome window at launch.
Check for updates automatically: at most once a day, Room 3D asks guidrygames.com whether a newer version is out. See Updates and release notes.
Snapping: how far a snapped move (metres), turn (degrees) and resize go at a time. 0.25 m, 15° and 0.1 to start with.
The view: the floor grid, the collision shapes and the lighting (the same as G, K and Shift+L).
Reset Panel Layout.

Changes apply at once and are kept for next time.

Projects (save and open)

A project file (.r3d) keeps the work in the editor, so it can be closed and opened again exactly as it was. The File menu has:

New Project (Cmd/Ctrl+N): an empty room, no models.
Open Project… (Cmd/Ctrl+O, or the folder button in the toolbar): opens a .r3d file in place of what's open.
Open Recent: the last eight projects opened or saved. Clear the list empties it. (The Welcome window lists them too.)
Save Project (Cmd/Ctrl+S, or the disk button): saves to the project's file (the first time, it asks where).
Save Project As… (Shift+Cmd/Ctrl+S): saves to a new file, which becomes the project's file.
Save As and Collect Model Files… (Alt+Cmd/Ctrl+S): Save As with Collect model files ticked (below).
Close Project (Cmd/Ctrl+W): an empty room (asks to save changes first).

A project keeps:

the Library: each model's file (where it is, and where it is from the project's folder), or which premade character it is;
the animations added to each model (from the Animation library and the like), stored inside the project file as they were made;
each model's marked animation events;
every thing in the room: its name, model, place, turn and size, GameMaker object, animation, loop setting and where its animation was, what it's attached to (the thing, the bone and its place on the bone), and its collision shape;
the view, the tool, the selected thing, and the GameMaker project and room the room was last saved to.

The project's name is shown in the window's title ("Room 3D — <project>") with a • after it while there are changes that aren't saved, and at the right of the status bar, beside Unsaved changes or Saved. Undoing back to where it was saved takes the • away. New, Open and closing the window ask first when there are unsaved changes: Save, Don't Save or Cancel.

Model files. Model files stay where they are; the project points at them. When it opens, each model is looked for beside the project first (at the same place relative to it), then where it was when the project was saved. A model that isn't found in either place is listed in a window, with Locate… to find its file; the things that use it are left out of the room until it's found. Saving the project in the meantime keeps them in it.

Collect model files: a choice in the Save Project As… window (ticked already with Save As and Collect Model Files…). It copies the model files into a folder beside the project (<project name>_models) and points the project at the copies, so the project and that folder can be moved to another computer together. Premade characters aren't copied (they come with the editor). For a glTF file, the buffers and pictures it names beside it are copied too; other formats are copied as one file.

A project can also be opened by dropping its file on the window, or by giving it on the command line.

A project is a ZIP file: project.json (readable, with a version) and the added animations in anims/.

Opening models

Add > Model from File… (Cmd/Ctrl+I, the cube button in the toolbar or the Library) opens 3D model files:

GLB / glTF: the best format. One file with its textures, skeleton and animations.
FBX: binary FBX opens directly. Older text FBX files, Collada (.dae) and .3ds open through Assimp, a free converter (in Terminal: brew install assimp).
OBJ: still models only (no animation; colours from .mtl files aren't read yet).

Models made in other units (centimetres, or tiny) are shown at a person's height. The file isn't changed.

The Library holds what's open (see Library). Its bin button (or Delete in the Library) takes a model out; if copies of it are in the room, it asks first and removes them too.

Export > Save Model as GLB… (Alt+Cmd/Ctrl+E) saves the Library's selected model as a GLB, with its animations (including any added from the library). It's the way to turn old FBX or OBJ files into GLB.

Premade characters

Room 3D comes with ready-rigged characters you can use straight away: no model file needed.

Mannequin: a plain grey figure with dark joints, mitten hands and a visor line on its face, made for testing animations.
Commando: a soldier in camouflage, with a helmet and goggles, a vest with pouches and a backpack.
Zombie: torn clothes, greenish skin, a hunched build and uneven arms.
Teen Adventurer (and Teen Adventurer B, other colours): hoodie, backpack, jeans, sneakers, messy hair.
Knight: plate armour, a great helm with a visor slit, a short tabard.
Robot: boxy plates, mechanical joints, glowing eyes and an antenna.
Townsperson A to D: everyday people in shirts and trousers, each with their own colours and hair, for crowds.

All of them share one skeleton, so an animation fits every one of them the same way.

C (or the person button in the toolbar or the Library): a menu of the characters, each with its picture. Add > Premade Character lists them too, and the Welcome window has a row of them.
Pick one: it joins the Library and a copy goes into the room, selected, playing its Idle.
Pick it again for another copy (or Cmd/Ctrl+D).

Every animation in the Animation library fits them: their skeletons use the usual humanoid bone names (Hips, Spine, Neck, Head, LeftArm, LeftForeArm, LeftHand, LeftUpLeg, LeftLeg, LeftFoot, LeftToeBase…), with a thumb and a two-part mitten on each hand and a toe on each foot. Add animations to it, then Save to GameMaker or Save model as GLB as with any model.

The characters are the files in the editor's characters folder (a GLB, and a PNG of the same name for its picture).

The view

Right-drag (or Alt + left-drag): turn the view around.
Middle-drag (or Shift + right-drag): slide the view.
Mouse wheel: zoom.
F: frame the selected thing. Shift+F: frame everything in the room.
1, 3, 7: look from the front, the right side or the top, flat (no perspective: lines stay parallel, good for lining things up). 5: back to perspective. Turning the view (right-drag) goes back to perspective too. The view's name is at its top left.
G: show or hide the floor grid. Shift+L: lighting on or off (off: flat colours, to see textures plainly). K: collision shapes.

The buttons at the view's top right do the same: the camera button for the views and framing, the sun for lighting, the eye for what's shown.

The grid lines are one metre apart, brighter every five. The red line is the x axis, the blue line the z axis; up is y.

Placing things

Add: double-click a model in the Library, or select it and press Enter.
Select: click a thing in the room, or in the Outliner. Esc selects nothing.
Move: drag a thing to slide it along the floor (with the Move tool).
Copy: Ctrl/Cmd+D (Edit > Duplicate) copies the selected thing (it keeps its animation and loop setting).
Remove: Delete (Edit > Delete, or the bin in the Outliner).

Each thing has a name, shown in the Outliner: its model's name for the first ("mannequin"), then the same with a number for each further one, added or copied ("mannequin_2", "mannequin_3"). Names are never shared in a room and are valid GameMaker names: GameMaker gets each as the instance's thing_name, and Attach to bone links by it.

It's renamed in the Outliner (double-click, or F2) or in the Inspector's GameMaker section.

The Inspector on the right shows the selected thing: its position, turn and scale, animation, collision shape, attachment and GameMaker object (see Inspector).

Move, turn and scale

Pick a tool in the toolbar, the Edit menu or with a key:

Select (Q): click things to select them; dragging doesn't move them, and no handles show.
Move (W): handles appear on the selected thing. Drag an arrow (red x, green up, blue z) to move along that axis only. Drag a square between two arrows to move in that plane; the green square slides it along the floor.
Turn (E): three rings. Drag a ring to turn the thing about that axis: green turns it like a turntable, red and blue tip it.
Scale (R): drag the thing up or down to make it bigger or smaller.

Snap (S, the magnet in the toolbar): on, moves go in steps of 0.25 m, turns of 15° and sizes of 0.1, by handles or by dragging the thing (the steps are set in Preferences). Off, hold Ctrl (or Cmd) while dragging to snap. The status bar says whether it's on.

The handle under the mouse lights up yellow. Handles follow the room's axes, and stay the same size on screen however far away the view is.

You can also type exact numbers in the Inspector's Transform section.

Collision shapes

GameMaker's own collisions are flat (2D). Room 3D gives each thing a 3D collision shape, saved to GameMaker with the room, where the kit's collision code (see GameMaker collision code) uses it: walls stop the player, it walks up ramps and stairs, a sword's hit finds the enemy.

The Collision section of the Inspector shows the selected thing's shape:

Shape (or Alt+K for the next one): None, Box, Sphere, Capsule (upright: for characters) or Mesh (the model's own triangles: ramps, stairs, rocks, a whole level piece). A mesh is simplified to at most 4,000 triangles when the model has more.
Fit (or Shift+K): fits the shape to the model again. Changing the shape fits the new one too.
Size (x, y up, z, in metres, before the thing's scale): a box's width, height and depth; a sphere's diameter (x); a capsule's diameter (x) and height from end to end (y). Only the sizes a shape uses can be edited.
Offset (x, y up, z): where the shape's middle is from the thing's origin.
Solid: ticked, the thing is level geometry (a wall, a floor, a crate, a ramp) that movers can't pass through. Not ticked, it's an actor (the player, an enemy, a pickup): found by collision checks, but not in the way of other movers.
Group: a word (enemy, pickup…) that GameMaker's collision checks can look for.
Show collision shapes (or K): draws every thing's shape in the view as a wireframe: solid ones orange, the others blue, the selected one brighter.

New things get a shape fitted to their model: characters (models with a skeleton) an upright capsule, not solid; other models a box, solid. A flat model (a floor) gets a box 10 cm thick under its top. Attaching a thing to a bone takes Solid off (it moves with the bone); in GameMaker an attached thing's shape follows the bone, so a sword's box can hit what it touches.

Shape changes can be undone, mark the project as changed and are kept in the project file. Copies keep the shape. Projects saved before collision shapes open with the fitted shapes.

In GameMaker each instance's creation code gets col_shape, col_size, col_offset (GameMaker units, x, y and z up), col_solid and col_group. A model used with Mesh gets its triangles in datafiles/room3d/<model>/collision.bin (kept on later saves, as other rooms may use them).

GameMaker collision code

The kit (scr_r3d) has 3D collision for things placed by Room 3D (and any o_r3d_thing). Units are GameMaker's (64 a metre), x and y are the room's, z is up.

Shapes (an instance's variables, set in Room 3D or in code)

col_shape: "none", "box", "sphere", "capsule" (upright, along the instance's own z) or "mesh" (its model's triangles).
col_size: [x, y, z]: a box's width, depth and height; a sphere's diameter (x); a capsule's diameter (x) and height (z). Before the instance's size.
col_offset: [x, y, z]: the shape's middle from the instance's origin.
col_solid: level geometry (true) or a mover/actor (false). col_group: a word.
Shapes turn and scale with rot_x, rot_y, rot_z and size. An attached thing's shape follows its bone and is never solid.

Moving

r3d_move(inst, dx, dy, dz): moves the instance's capsule (or sphere, or the upright box around a box) by that much, stopped by solid things and sliding along them: along walls (the part of the move along the wall is kept), up steps up to step_height (20 units to start with), up slopes up to slope_limit (46 degrees) without sliding back, down steps and slopes without leaving the ground, and off edges (it falls: add gravity to dz each step). Fast moves are taken in small steps, so nothing thin is passed through. Sets on_ground, ground_nx/ny/nz, hit_nx/ny/nz and hit_inst; returns {hit, on_ground, wall, ceiling, nx, ny, nz, inst}.
r3d_on_ground(inst): whether it stands on something walkable.

Finding things

r3d_collide(inst, group = undefined): every instance its shape touches now (not things attached to it, nor what it's attached to), all of them or one group's.
r3d_place_meeting_3d(inst, x, y, z, group = undefined): whether it would touch anything at (x, y, z). r3d_instance_place_3d(...): the first instance it would touch, or noone.
r3d_raycast(x, y, z, dx, dy, dz, dist, ignore = noone, group = undefined): the first shape along a ray (ignore: an instance or an array of them). Returns {hit, x, y, z, nx, ny, nz, inst, dist}.

The collision world

Solid things go into a grid the first time anything is asked in a room. A solid thing that moves, turns or changes size is put in again on its next step; r3d_collision_update(inst) does it at once, r3d_collision_add(inst) / r3d_collision_remove(inst) add or take out one, r3d_collision_build() (or r3d_collision_rebuild()) makes it all again.
r3d_collision_debug(on) (no argument: switch) draws every shape over the room: solid things orange, movers blue, attached things yellow, a mover touching something red. r3d_collision_debug_on() says whether it's on.

Example: a player

Create: event_inherited(); vz = 0;

Step: event_inherited(); vz -= 9.8 * 64 * dt; if (on_ground && keyboard_check_pressed(vk_space)) { vz = 256; } r3d_move(id, mx, my, vz * dt); if (on_ground && vz < 0) { vz = 0; }

A sword's hit (on the Attack's "hit" event): var hits = r3d_collide(sword); for (var i = 0; i < array_length(hits); i++) { if (hits[i].object_index == o_enemy) { hits[i].hurt(); } }

The test project's rm_r3d_demo does all of this: walls, crates, a ramp and stairs up to a platform, a mound, a training dummy hit by the sword (o_demo_player, o_demo_dummy). C there shows the shapes.

Undo and redo

Undo: Cmd/Ctrl+Z, Edit > Undo, or the Undo button in the toolbar.
Redo: Shift+Cmd/Ctrl+Z or Ctrl+Y, Edit > Redo, or the Redo button.

While typing in a box, Cmd/Ctrl+Z undoes the typing; once you've left the box, it undoes the change to the room.

Undo covers renaming, moving, turning and resizing (a whole drag is one step; typing in a number box is one step), adding, copying and removing things, GameMaker object names, the animation choice, the loop setting, attaching to bones, and collision shapes (shape, fit, size, offset, solid, group). The last 200 steps are kept.

Not undoable: removing a model from the Library, adding an animation to a model from the library, and animation events (remove them in the Events window).

Animations

Each thing plays one animation, picked in the Inspector's Animation section (Clip). The Timeline under the view controls it:

Go to Start (Home) and Play / Pause (Space).
Loop (or L): on, the animation repeats with no pause between rounds; off, it plays once and holds its last frame (the bar shows "once"). Each thing has its own setting, and it's saved to GameMaker.
The clip's name, then the slider: drag to scrub through the animation, frame by frame. Gold marks over it are the animation's events. On the right: the time and the frame (30 a second).
Events… (or M): mark named events on frames (see Animation events).

Many animations (Mixamo's among them) end on a copy of their first pose. When looping, Room 3D skips that copy so there's no hitch.

Animation library

Animation > Animation Library… (Cmd/Ctrl+L, or the books button in the toolbar) lists animations you can add to a character, from your own folders of animation files: every FBX, GLB or glTF file in a folder and the folders inside it. Press Choose… to pick the folder; the window remembers the last one.

Where animations come from: Mixamo (free, with your Adobe account: download them from mixamo.com into a folder), Meshy's animation library with your own Meshy account, or your own files, for any humanoid skeleton.

Grid and List (top right, or Cmd/Ctrl+G) switch between two views; the window remembers which:

Grid: a moving picture of each animation, under a heading for each folder, with its name (and, where known, its length and "in place" where it stays put). A faint floor grid slides under the figure as it travels, so walking forward and walking in place look different.
List: the names, in their folders.

In the grid:

Rest the mouse on a picture: a larger one plays beside it at full speed, with where the animation comes from.
Click a picture to try it (as clicking a name does), double-click to add it. The arrow keys move between pictures and Enter adds.
Size (bottom right, or Cmd/Ctrl + and Cmd/Ctrl -): smaller pictures to see more at once, larger to see more detail.
On the Mannequin / On the selected character: what the pictures show the animations on. The Mannequin is the premade one; "the selected character" makes them again on the character selected in the room (when nothing is selected, the Mannequin is used). Animations whose skeleton has no usual humanoid bone names show on a plain stick figure.

Each picture is made the first time it comes into view (a moment, shown by three dots) and kept, so scrolling past it again is instant, even after restarting.

To use it:

Select a character in the room.
Search (every word must match a file's name or folder: "jump", "zombie attack", "crouch walk").
Click an animation: the character plays it at once, fitted to its own skeleton.
Add to model (or double-click) keeps it, under the name shown (you can change the name). Every copy of that model in the room gets it, and it's saved with Save to GameMaker and Save model as GLB.

In place takes the travel out of an animation that moves across the ground (the game moves the character instead).

Animations fit any humanoid skeleton with the usual bone names (Mixamo, the premade characters and the like), even if its rest pose or proportions differ.

Combining animations

Animation > Combine Animations… (Shift+Cmd/Ctrl+L, or its toolbar button) makes one model with many animations from separate downloads (Mixamo: the character "with skin", each animation "without skin"). It saves a GLB and an FBX side by side; Blender (installed in Applications) does the work in the background.

Character: the file with the skin. Its own animation is kept, named after the file.
Animations: Add… the animation files (each named after its file).
Keep in place: takes out the travel; the bounce stays.
Arm spacing: see the Arm spacing topic.
Save as: where the GLB goes (a "Combined" folder beside the character, if you don't choose).

Press Combine. When it's done, the new model opens and goes into the room.

Arm spacing

Like Mixamo's "Character Arm-Space": swings the upper arms away from the body (or in towards it, below zero) in every animation, so arms don't pass through a wide body. The forearms, hands and anything held follow.

In the Combine animations window, drag Arm spacing: the character selected in the room shows it at once. Combine writes it into the animations. Reset puts it back to 0.

Save to GameMaker

Save to GameMaker (the gold button at the right of the toolbar, Export > Save to GameMaker… or Cmd/Ctrl+E) saves the room; Export > Save Model to GameMaker… (Shift+Cmd/Ctrl+E, see its own topic) saves one model. The GameMaker project and room are remembered, and kept in the Room 3D project too.

Saving the room asks for the project's .yyp file and a room name, then adds to the project (nothing of yours is removed):

the models, baked for GameMaker, with every animation and its marked events (in datafiles/room3d/);
the Room 3D kit: the script scr_r3d, the shader sh_r3d, the objects o_r3d_thing and o_r3d_scene (written again on every save: don't edit them; make your own objects children of o_r3d_thing);
an object for each GameMaker object name in the room that the project hasn't got, a child of o_r3d_thing whose Create event names its model (your own objects are left alone);
the room, with each thing's model, animation, loop, height, turn and size in its creation code (and, for an attached thing, what it's attached to; and its collision shape), and a camera where the editor's view is.

The room is written again on every save, but what you added to it in GameMaker stays: any layer other than Room 3D's own (Things, Scene and the backdrop), such as an instance layer with a HUD or a game controller, is kept with its instances and their creation code, and so is the room's creation code.

Names are compared without case, as GameMaker does on a Mac (where o_zombie and o_Zombie are the same file). When a name is taken by something else — another model's folder, an object that isn't this model's, or a room Room 3D didn't make — the save uses the name with a number instead (zombie_2, o_zombie_2) and the message at the bottom says so. The next save finds the same names and uses them again. If GameMaker's ProjectTool rejects the project, the .yyp is put back as it was.

A model's folder is shared by every room that uses it: saving it again (from any room) replaces its animations for all of them, so keep every animation those rooms play on the model.

In GameMaker, animations blend into each other, can play once and say when they've finished, and run events marked on their frames: see GameMaker animation code.

Sizes: 64 GameMaker units per metre; x and y are the room's, z is up. Turns: GameMaker's matrix_build turns the other way round about each axis (and about y, then x, then z), so the creation code's rot_x, rot_y and rot_z are worked out to give the same turn as in Room 3D: a turn of 35° about up is rot_z = -35.

Save model to GameMaker

Export > Save Model to GameMaker… (or Shift+Cmd/Ctrl+E) writes just one model into a project, for use in your own rooms: no room is made or changed.

Pick the model (the one selected is picked for you) and the project's .yyp.
Leave Also make an object ticked to get an object for it (o_<model>, a child of o_r3d_thing whose Create event names the model and its first animation). An object the project already has is left alone. If the name is taken by something else (names are compared without case), the model and object get a number instead (zombie_2, o_zombie_2; see Save to GameMaker).
Save: the model goes into datafiles/room3d/<model>/ with its animations and events, and the Room 3D kit is written too.

Then, in GameMaker:

Place the object in any room, with an o_r3d_scene for the 3D camera (or your own camera). Set z, rot_z, size or anim in the instance's creation code.
Or make one in code: r3d_create(x, y, z, "mannequin", "Idle"), or instance_create_depth(x, y, 0, o_r3d_thing, { model: "mannequin", anim: "Idle" }) (variables in the struct are kept).

Attach to bone

A thing can follow a bone of another thing: a sword in a hand, a hat on a head, a lamp on a moving part.

Put both in the room and place the sword where it should sit in the hand (with the character in the pose you want to fit it to).
Select the sword and press Attach to Bone… (the Inspector's Attach to bone section, Animation > Attach to Bone…) or P; or drag the sword onto the character in the Outliner.
Pick the thing that carries it and the bone (type in the search box: "hand", "head"). Its right hand is picked first if it has one.
Attach: it stays where it is and follows the bone from now on, through every animation. Tick Move it onto the bone to put it exactly on the bone instead.

Follows in the Inspector shows the thing and bone, and the Outliner shows it under its carrier. Move or turn an attached thing as usual: it keeps its new place on the bone. Detach (the Inspector, the same window, Shift+P, or dragging it onto empty space in the Outliner) lets go; it stays where it is. Attaching and detaching can be undone.

Save to GameMaker writes it into the room: the attached instance's creation code has attach_to (the carrier's name), attach_bone and attach_offset, and it follows the bone in GameMaker too, with blending. In code: r3d_attach(sword, player, "RightHand").

The bones are the skeleton's (a model without a skeleton: the parts its animations move). Things can't carry each other round in a circle.

Animation events

Mark named moments on an animation's frames: a footstep, the frame a punch lands, a sound. In GameMaker each event runs once as the animation passes it.

Select a thing and pick the animation.
Scrub to the frame with the slider, then Events… (the flag at the right of the Timeline, the Inspector's Animation section) or M.
Type a name (step, hit…) and press Add at frame N (or Enter). It shows as a gold mark over the slider.

In the Events window, click an event to go to its frame; Remove takes it off. Frames are counted at 30 a second, as in the bar.

Events belong to the model's animation (every copy shares them) and are kept between sessions for that model file, and in the project file. They're saved with the model by Save to GameMaker and Save model to GameMaker.

In GameMaker, each event fires once per pass (also at high speed, in big steps, looping, backwards and while blending): on_anim_event(name) runs, then User Event 14 (with anim_event set to the name), and anim_events_fired lists the step's events. See GameMaker animation code.

GameMaker animation code

Everything below is in the kit (scr_r3d) that Save to GameMaker writes. Use it in an o_r3d_thing or a child of it (call event_inherited() in your Create, Step and Draw events).

Playing

r3d_play(anim, loop = true, blend = anim_blend, restart = false): plays an animation, blending from the pose the instance is in over blend seconds (0: switch at once). Asking for the one already playing does nothing (so it can be called every step), unless restart is true or it has finished.
anim_blend: each instance's blend time (0.2 s to start with). Setting anim = "Run" directly blends too.
r3d_anim_done() or anim_done: true when an animation played once (loop false) has reached its end. It then holds its last frame.
on_anim_end = function(anim) { ... }: runs at that end (then User Event 15).
on_anim_event = function(name) { ... }: runs at each marked event (then User Event 14, anim_event is the name). anim_events_fired: the events passed this step.
anim_time (seconds in), anim_speed (1: as made; negative plays backwards), anim_loop.

About models

r3d_model(name): a model (loaded once). r3d_anim_names(model), r3d_anim_length(model, anim) (seconds), r3d_anim_events(model, anim), r3d_bone_names(model).
r3d_create(x, y, z, model, anim = "", object = o_r3d_thing): an instance, made in code.

Bones

r3d_bone_matrix(inst, bone): the bone's matrix in the room now (animation, blending, the instance's place, turn and size; axes of length 1), or undefined. For drawing your own vertex buffer in a hand: matrix_set(matrix_world, r3d_bone_matrix(player, "RightHand")), then vertex_submit. Where it is: matrix_transform_vertex(m, 0, 0, 0).
r3d_attach(child, parent, bone, offset = matrix_build_identity()): child (an o_r3d_thing) follows the bone, offset from it (a matrix in the bone's axes). r3d_detach(child) lets go. Or set attach_to, attach_bone, attach_offset on the child.

Example: a player

Create: event_inherited(); on_anim_end = function(a) { r3d_play("Idle"); }; on_anim_event = function(n) { if (n == "hit") { hurt_enemies(); } };

Step: event_inherited(); if (keyboard_check_pressed(ord("J"))) { attacking = true; r3d_play("Attack", false, 0.15, true); } else if (!attacking) { r3d_play(moving ? "Walk" : "Idle"); } (and attacking = false in on_anim_end).

Camera: o_r3d_scene.follow = player makes the room's camera follow it (follow_z above its feet; right-drag still turns it).

The test project's rm_r3d_demo is a whole example: the Mannequin walked with WASD / arrows, Shift to run, Space to jump, J to attack with a sword in its hand (its object o_demo_player).

Lights, fog and culling (GameMaker)

The kit draws things lit from above in their own colours. For night scenes, torches and flashlights, turn on its lighting in your game's code (scr_r3d, nothing to set in the editor):

r3d_lighting(true): the room's lights and fog from now on (false: the plain look again).
r3d_ambient(r, g, b): the light everything gets (0-1 each: 0.05 is a dark night).
r3d_sun(dx, dy, dz, r, g, b): a far light from that direction (towards it; z is up): the sun or the moon.
r3d_fog(r, g, b, start, end, max = 1): things fade into that colour from start to end units from the camera. r3d_fog_off().
r3d_light_clear(), then r3d_light_add(x, y, z, radius, r, g, b, strength = 1) for each point light (a campfire, a lantern, a glow round the player): up to 8, so add the nearest first. Set them again each step when they move or flicker.
r3d_spot(x, y, z, dx, dy, dz, range, inner, outer, r, g, b, strength = 1): one spotlight, a cone from (x, y, z) towards (dx, dy, dz): full strength inside inner degrees of its middle, fading out to outer. r3d_spot_off().

Each instance also has:

tint: a colour its colours are multiplied by (c_white as made; make_colour_rgb(60, 60, 70) for a shadowy figure);
emissive (0-1): shown in its own colours, unlit (flames, glowing eyes, a lit window);
flash (0-1) and flash_colour: a colour added on top, e.g. a white flash when it's hit (let it fade).

Culling: things out of sight aren't drawn: behind the camera, outside its view, or further than r3d_cull_distance(units) (0: no limit; with fog, its end). o_r3d_scene tells the kit where the camera is; a camera of your own calls r3d_eye(x, y, z, look_x, look_y, look_z, fov, aspect) each step. An instance with cull = false is always drawn. It works from the sphere round each model, saved in its model.json (models saved before this are always drawn: save them again). r3d_light_state().drawn and .culled count what was drawn and skipped.

Account and licence

Room 3D is sold on guidrygames.com, and your licence belongs to your Guidry Games account (the same account as on the website).

Sign in: Room 3D > Sign In… (on a Mac) or Help > Sign In…. Type your email and password. Create an account… and Forgot your password? open the website. Signed in, the same item shows Account (your email)…, with Sign Out. The password is sent only to guidrygames.com and isn't kept; the sign-in itself is kept in the Mac's Keychain.
The Licence window: Room 3D > Licence… or Help > Licence…, or click the licence note in the status bar. It shows whether Room 3D is in its free trial, licensed, on a subscription, or in free mode, until when, your account and this computer. Its buttons: Buy Room 3D…, Enter Licence Key…, Check Now, Manage Computers… (your account page) and Sign In….
One licence, two computers: a licence works on two computers at once. To use a third, sign out on one (Account… > Sign Out) or remove one under Manage Computers… on the website.
Offline: Room 3D checks your licence with guidrygames.com every few days, in the background. Without the internet it keeps working for 30 days after the last check; then the Licence window asks you to connect and choose Check Now.

The free trial

Everything works for 7 days of use: a day counts when Room 3D is opened that day, so days you don't use it don't count. The status bar and the Licence window show Trial: 3 of 7 days used. The days are counted for this computer and for your account (so reinstalling doesn't start a new trial).

Free mode

After the trial, Room 3D keeps working: open, change and save your projects, try animations, everything in the editor. Only Save to GameMaker, Save Model to GameMaker and Save Model as GLB need a licence: choosing them shows the Licence window, with Buy Room 3D… and Enter Licence Key…. Nothing you made is ever locked away.

Buying and licence keys

Help > Buy Room 3D… opens the Room 3D page on guidrygames.com. Buy it once, or subscribe, when both are offered. Sign in on the website first (or buy with your account's email), then sign in here with the same account: the licence arrives by itself (or choose Check Now in the Licence window).
Licence keys (they look like R3D-XXXXX-XXXXX-XXXXX-XXXXX): Help > Enter Licence Key…, sign in if asked, type the key and choose Use Key. Capitals, spaces and dashes don't matter, and the key has no O, I, 0 or 1 to mix up. A key becomes your account's: it works on your computers, and nobody else can use it after you. Your account page on the website lists the keys you've used.
A subscription stays active while it's paid; if it ends, Room 3D goes to free mode (your projects stay yours).

Updates and release notes

Room 3D > Check for Updates… or Help > Check for Updates… asks guidrygames.com whether a newer Room 3D is out. If one is, a window shows what's new, with Download (it opens the download in your browser; install it like the first time), Skip This Version and Later.
Room 3D also checks by itself, at most once a day, and only says something when there's news. Turn it off in Preferences.
Help > Release Notes opens the list of what's new in every version, on guidrygames.com.

Help and support

Room 3D Help (F1): this window, with a search.
Room 3D Manual (Web) (Shift+F1): the same topics as a web page on guidrygames.com, to read in the browser or print.
Keyboard Shortcuts (Cmd/Ctrl+/): every key in one list.
Report a Problem…: a new email to hello@guidrygames.com in your email app, with your Room 3D and macOS versions filled in. Say what you did, what happened and what you expected; a project file or a picture helps.
guidrygames.com: the website. About Room 3D: the version, and the open-source parts in Room 3D.

Keyboard shortcuts

Every menu item shows its shortcut, and every toolbar button says it when the mouse rests on it. Keys without Cmd/Ctrl work anywhere but while typing in a box.

Tools and editing

Q / W / E / R: Select, Move, Turn, Scale tool.
S: Snap on / off. Ctrl/Cmd while dragging: snap once.
Delete / Backspace: remove the selected thing. Cmd/Ctrl+D: copy it. F2: rename it. Esc: select nothing.
Cmd/Ctrl+Z: undo. Shift+Cmd/Ctrl+Z or Ctrl+Y: redo.
K: show or hide the collision shapes. Shift+K: fit the selected thing's shape to its model. Alt+K: its next shape (none, box, sphere, capsule, mesh).
Cmd/Ctrl+,: Preferences.

The view

F: frame the selected thing. Shift+F: frame everything.
1 / 3 / 7: front, side, top (flat). 5: perspective.
G: grid. Shift+L: lighting.
Cmd/Ctrl+1 / 2 / 3 / 4: show or hide the Outliner, the Library, the Inspector, the Timeline. Cmd/Ctrl+Alt+0: reset the panels.
Ctrl+Cmd+F (Mac) or F11: full screen.

Adding

C: the premade characters (with pictures). Cmd/Ctrl+I: a model from a file. Enter: another copy of the Library's selected model.

Animation

Space: play / pause. Home: go to the start. L: loop on / off.
M: mark an animation event (the Events window). P: attach the selected thing to a bone. Shift+P: detach it.
Cmd/Ctrl+L: the Animation library. Shift+Cmd/Ctrl+L: Combine animations.
In the Animation library: Cmd/Ctrl+G grid or list; Cmd/Ctrl + / - bigger or smaller pictures; arrows and Enter move between pictures and add one.

Projects and GameMaker

Cmd/Ctrl+N: new project. Cmd/Ctrl+O: open. Cmd/Ctrl+S: save. Shift+Cmd/Ctrl+S: save as. Alt+Cmd/Ctrl+S: save as, collecting the model files. Cmd/Ctrl+W: close the project.
Cmd/Ctrl+E: save the room to GameMaker. Shift+Cmd/Ctrl+E: save one model to GameMaker. Alt+Cmd/Ctrl+E: save a model as GLB.

Help

F1: this help. Shift+F1: the manual on guidrygames.com. Cmd/Ctrl+/: this list. Shift+Cmd/Ctrl+H: the Welcome window.

Mouse: right-drag turns the view, middle-drag (or Shift + right-drag) slides it, the wheel zooms.