Documentation by TAPgiles

# Puppet

Puppets are the basis for most characters in Dreams. They give us procedural walking, and basic actions like jumping.

The puppet object is like a group, and so uses the same scope rules and controls. When scoped in, shows a circular purple base with a point toward the “front” of the puppet. We can tweak this base or the puppet object itself to adjust the puppet’s settings.

This object can only be created by importing one of Media Molecule’s puppets and editing it.

Normally puppets have a puppet rig: sculpts jointed together to form a skeleton the puppet object can animate. (Tg)

We can also use the Stretch tool (without editing the sculpt itself) to quickly adjust the proportions of the puppet. (Mm) (See the Character Art tutorial.) And add objects to body parts by using the auto-grouping functionality. (Mm)

The puppet is told to move in different ways by sending signals into any Puppet Interface gadget that is inside the puppet object.

You can turn a regular puppet into a first-person puppet. By making the head invisible, adjusting its controller sensor’s camera distance, and turning on the “face camera” setting. (Tg)

While a puppet is possessed and the camera view is too close to it, it will fade out and disappear so that the view is not obscured. (Tg)

# Puppet Mirror: When scoped into a puppet group, this context menu button toggles the puppet mirror feature.

When on and manipulating linked body parts, the opposite body part will be manipulated in a flipped way across the central line of the puppet’s chest object. (Tg) (Eg. moving the right hand up will move the left hand to the same height.)

Memory: Costs 0.0937% of the things limit per gadget. Costs 1 of 256 of the unique stamped elements limit per kind of Mm puppet imported.

Performance: Procedural animation and collision costs on performance, and so has a limit to how many full puppets can function at once.

Procedural Animation

“Procedural” animation is animation based on rules concerning how the puppet is moving, if they are on a surface, etc.

This means that even if the puppet object is animated around the place, those same rules are in place and the animation still works.

With all procedural settings on, the puppet will be animated in the following ways:

  • Idle: While on the ground and not moving, the puppet will transition to the original pose of the character.
  • Walking: While moving, the puppet will animate a walk cycle. Works the same while “running”.
  • Flying/Jumping: While not on the ground, the puppet will have poses and animations dependent on if it is moving up, down, or not moving.
  • Looking: Turning the head and torso to look towards the imp and tags within the scene.

These procedural animations can be further finessed by the tweak menu settings on the puppet object. And by using a Puppet Interface to animate the poses to animate from, and the tweak menu settings.

# Mm Blank Puppets

There are different kinds of puppet Media Molecule has created that we can import from the gadgets menu. (Mm) For each of them, the sculpts used for the limbs on their left side are live clones of the limbs on their right side, and flipped.

This makes it easy to edit the body part sculpts and create a whole new character, without having to edit both sides.

These can all be built from scratch with the tools and a puppet object.

Blank Puppet (Basic)

Tan colour body parts (like wood or clay).

Has a running pose, and audio-surface sensitive sound effects for jumping, landing, and footsteps.

Left stick or Secondary Gyro to walk and run. Use Cross to jump. Controller gyro to lean/twist. Use Circle to de-possess.

Respawns the puppet when it has no health, or when it has fallen out of the scene.

Blank Puppet (Deluxe)

Also has an idle pose, and jump poses for ascent, peak, and descent.

When its Level Complete tag is detected, triggers a victory pose and a camera shot that blocks controls and the imp.

While possessed, “Follow me,” “Look at me,” and “Possessed puppet” tags are powered.

Unless possessed, auto jump is on and follow is on.

Blank Sliding Platforming Puppet

A small Chibi-style character. Settings are adjusted for a tighter platforming experience. A “Sliding Behaviour” chip has been added allowing the puppet to slide on its back down slopes that are steep enough.

Click here to View on

# Quick Edit

At the bottom of the Overall Movement, Upper Body Movement, and Lower Body Movement tabs is a “Quick Edit” menu. The state corresponding to whichever is lit up will be previewed, making it easy to adjust things as you see its effect.

If a keyframe is powered by the corresponding output from the Puppet Interface, you will start recording into the keyframe created first.

While time is running, previews the state in motion while not moving the puppet. (Tg)

The menu is a Selector with the following options:

# Flipping Issues

When a puppet has been flipped, it can then respawn at an odd angle before righting itself. To fix this, unflip the puppet. (Tg) Instead, clone and flip the limbs. Scope into the torso group and flip everything inside it, things like that.

# Overall Movement Tab

# Walk Speed, Run Speed

For movement under its own power (not falling, sliding, or being shoved by physics forces), the higher of the two settings is key. I'll refer to this as the “Max Speed.”

The puppet is told to move by signals going into the Puppet Interface gadget’s Walk input, from a range of 0 - 1. When that signal is at 1, the puppet will accelerate to max speed. At a lower percentage signal, the puppet will accelerate/decelerate to that percentage of max speed. (Tg)

# Turn Speed

How fast the puppet turns whenever it tries to turn.

At 0, the rotation of the puppet is not controlled in any way.

Because of this, if a puppet was rotating when suddenly control was cut and the rotation speed set to 0, the puppet may continue to rotate. To slow the rotation in these cases, use a Rotator with 0 speed and high damping to slow the puppet's rotation.

# 2D Movement

When on, normal puppet controls can only move the character left and right parallel to the X axis of the scene.

Note that pushing up or down on the stick to walk is still possible, but the up/down component of the direction is ignored. Because of this, when the player pushes the stick not perfectly right or left, the puppet will move slower in that direction. To snap it to full speed left or right, logic may be used to construct a fake stick direction. (Tg)

The plane of movement allowed for the puppet is the Z plane at whatever depth the puppet was the moment this setting was turned on.

Works similarly to a setup using a follower, which can be used for any object—not just puppets. (Tg)

# Face Camera While Idle

When on, the puppet will turn towards the camera while possessed and idle.

# Face Camera Direction

When on, the puppet will turn away from the camera while possessed to face the same direction the camera is facing.

# Acceleration, Deceleration

How quickly the puppet increases its speed. And how quickly the puppet reduces its speed either to slow down, or change direction.

# Jump Height

The height of a full jump.

A jump is triggered by a signal being sent into a Puppet Interface gadget’s Jump input.

Note that if gravity is set to 0%, the puppet will be unable to jump.

The jump and double-jump could be made completely custom by implementing it using a mover, and the animations will work just as normal. (Tg)

# Min Jump Height

The minimum height relative to the Jump Height setting. As the jump signal continues, the puppet will keep getting higher to a maximum of Jump Height.

For example, Cross button is wired to tell the puppet to jump using a puppet interface. If the player taps Cross button for as short a time as they can, the puppet will reach the “minimum jump height.” If the player holds Cross button until the puppet reaches the top of their jump, the puppet will reach “jump height.”

# Double Jump Height

When at 0, has no effect.

When at a positive distance, how high the puppet will double-jump in the air, if it has not already double-jumped since it left the ground.

When the puppet stands or runs on the ground, this will be reset and it is able to double-jump again.

There is no way of resetting this through logic. Logic can be created to make your own double jump for a more custom mechanic. (Tg)

# Gravity

How much effect the global gravity of the scene will have on the puppet.

Commonly set to > 100% for a more tight, arcadey feel.

# Air Control

How much the puppet’s direction can be controlled while in the air through a Puppet Interface gadget’s Walk input.

For example, if set to 0%, while the puppet is in the air any input by the player will not affect the puppet’s trajectory.

If the player tries to steer the puppet and it is moving faster than its run speed, it will slow down. If that is undesired, we can turn up the run speed while it’s meant to be moving fasterin the air, turn down the deceleration setting. Or we can block the input going into the puppet interface’s “Walk”.

# Walkable Slope

The puppet will slide off of ground that is steeper than this value.

# Sliding Friction

When the puppet is sliding down a slope it cannot walk up, how fast the puppet will slide down it. Or, how “slippery” the slope appears to be.

# Camera Follow When Sliding

When on, the camera will follow the puppet as it slides down an incline. It will also not be considered to have fallen out of the scene, while sliding.

When off, the camera will not follow the puppet vertically when sliding.

# Lower Body Movement Tab

# Slideyness

While accelerating, the legs’ procedural animation will act as though it is moving at some percentage of full speed. So if it takes a while to get going and the puppet has high slideyness, it will appear as though it is running on the spot. (Tg)

# Skateyness

Reduces the effect of the legs’ procedural animation. (Tg)

# Match Floor Angle

While supported by a sculpt, how much will the puppet’s pelvis tilt (and therefore the rest of the puppet in most circumstances) to match the angle of the sculpt’s surface. High means the puppet will appear perfectly perpendicular to the surface. Low means the puppet will attempt to stay upright. (Tg)

# Lean Into Strength

How much the puppet will lean into a turn. Low means it will stay upright. High means it will lean hard into any change in acceleration. (Tg)

# Feet Separation

How far apart the feet will be when walking or running. Low means the puppet will walk one foot directly in front of the other. (Tg)

# Bicycle Feet

How much the feet move in a circular motion while walking, as if pedalling a bicycle. (Tg)

# Stompyness

How high the feet get at the extremes of each stride. (Tg)

# T-Rex Tread

When on, the feet will move up slowly, and quickly slam down to the ground. (Tg)

When off, the feet will move up quickly and slowly sink to the ground.

# Strideyness

How large each stride is. Low strideyness means the puppet will take tiny steps. (Tg)

# Min. Stride Time

The minimum time each stride takes. Ensures the steps don’t get too short and quick for a larger, heavier, slower character. (Tg)

Also useful to ensure the puppet doesn’t step too quickly while strafing left or right. (Tg)

# Centre of Gravity

Moves the hips’ at-rest position up or down. (Tg)

# Bounciness

How much the pelvis is moved down when a foot hits the ground. Negative will move the pelvis up when the foot hits the ground. (Tg)

# Upper Body Tab

# Motion Sensor Movement

How much the lean input of the puppet interface affects the lean of the puppet. (Tg)

# Lean Lag

How far the head can tilt from Motion Sensor Movement (which comes from the Lean input), before the rest of the body begins to tilt with it. (Tg)

# Sassyness

How much the shoulders and hips rotate in opposite directions to each other while walking. (Tg)

# Sway

How much the puppet leans side to side from the hips as steps are taken. (Tg)

Better with higher foot separation or a wider pose for the feet.

# Lumberingness

How much the shoulders lean side to side as steps are taken. (Tg)

# Stiffness

How much the spine (specifically, joint between the belly and chest) ignores procedural animation—affecting animations that turn the head and the spine and body follows. (Tg)

# Arm Vigour

How much the arms rotate forward from the hands while walking. (Tg)

# Arm Flail

How much the arms rotate at the shoulders while walking. (Tg)

# Springiness

How floppy the joints are. Similar to joint springinessbut does not affect the joint settings themselves. (Tg)

# Breathyness

How much the puppet is affected by the breathing rhythm of approximately 3.8 seconds (from starting to breathe in, to breathing out completely and starting a new cycle). (Tg)

# Anticipate Turn

How quickly the head turns faster than the body, when the puppet turns. (Tg)

# Body Structure Tab

If a part is not associated, it will appear faded.

If a part is associated or it cannot lead back through other properly linked parts to the pelvis it will not be affected by the procedural animations and the button will appear greyed out.

At least one heel must be correctly set up for the arms to procedurally animate.

Unless a body part is set as a body part, it will simply respond physically in an uncontrolled way and “ragdoll.” However, these buttons and associations cannot change during play. Therefore, to have a character “ragdoll,” another ragdolling object must replace it. (Tg)

# Behaviour Tab

# Auto Jump

When on and moving across the ground towards a hole that the puppet can jump over at its current speed and jump height setting, it will jump.

# Auto Look

If there is no tag target found for the Look At setting, the head will look towards the imp while the imp is close enough and in front of the head. (Tg)

# Follow

When on, the puppet will move towards the closest powered Tag with the correct name within range until it is within the minimum distance. (Tg)

The tag is not considered “detected” while being targeted by this setting.

To make a puppet flee from a tag instead of follow it, Follower and Rocket Rotator gadgets can be used instead. (Tg)

# Follow: Inner Radius, Outer Radius

A Tag must be inner < tag distance < outer to be targeted by the follow behaviour.

# Turn Towards

When on, the puppet will turn to face the closest powered tag with the correct name within range. The “front” of the puppet is denoted by the point of the purple base within the puppet group.

Overrides the received Turn to Face direction.

# Turn Towards: Outer Radius

A Tag must be tag distance < outer radius to be targeted by the Turn Towards behaviour.

# Look At

When on and Auto Look is on, the puppet’s head will turn to look at the closest powered tag with the correct name within range. (Tg)

# Look At: Outer Radius

The maximum distance a tag can be from the puppet to be targeted.

# Procedural Animation

When on, allows procedural animation to work. (Tg)

# Procedural Walk

When on, walking and running will be animated automatically, and Procedural Jump can work. (Tg)

# Procedural Jump

When on, jumping will be animated automatically. (Tg)

# Physical Properties Tab

A puppet has a special “pill” shape for the collision of a puppet used not for colliding with the ground but with other objects. To preview this shape, hover over any of the collision shape settings.

# Collision Shape: Vertical Position

How far up from the ground (purple base) the pill shape begins.

# Collision Shape: Height

How tall the pill shape is from end to end. As the width is a radius measured from the centre, the pill has a minimum height relative to the set width.

# Collision Shape: Width

The radius of the collision pill shape.

The shape of the bottom and top are half-circles with this same radius.

# Puppet Interface

Sends commands and receives data from the puppet group the gadget is inside.

Memory: Costs 0.0085% of the things limit per gadget.

# Inputs Tab

# Walk

Tells the puppet to move in a direction on the X-Z plane (not up and down). The signal's magnitude (distance from 0) is also used.

The target speed of the movement is the signal magnitude × puppet max speed. (Tg)

# Turn to Face

Tells the puppet a particular direction to face. (Tg)

Good for quickly making twin-stick controls. (Tg)

# Lean

Tells the puppet to rotate its head to a certain angle.

Commonly, the Controller Sensor gadget’s Motion Sensor setting is wired into this, allowing the player to tilt the controller to have their puppet look around expressively.

The signal is multiplied by the Motion Sensor Strength.

To turn this feature off entirely, remove the wire going into this setting.

# Go Forwards, Go Backwards

Tells the puppet to move in the direction it is facing or move backward away from the direction it is facing. The speed the puppet will actually move is dictated by its walk and run settings.

# Jump

Tells the puppet to jump.

# Outputs Page 1

# Jumped

Sends a pulse when the puppet jumps from on the ground because of an input into a puppet interface’s “jump”. The fat wire represents a collision with the surface the puppet left when jumping.

# Double Jumped

Sends a pulse when the puppet jumps again after jumping from the ground, if the settings allow a double-jump.

# Landing Impact

Sends a pulse when the puppet’s feet land onto a collidable surface.

Fall damage can be implemented using this. (Tg)

# Predicted Landing Impact

The force the puppet is predicted to land with. Useful for triggering effects in preparation for a hard landing.

# Fell Out of Scene

Sends a signal if the puppet has nothing below it within the scene’s maximum fall height that it can collide with.

# Distance from Ground

Sends the distance of the nearest object the puppet can collide with below the puppet, as a percentage of the containing Puppet’s Jump Height.

# Idle Strength

The puppet is considered “idle” while not moving, trying to move, or in the air.

Transitions to 1 while idle over roughly half a second. Transitions to 0 while not idle.

# Walking Strength, Running Strength

Walking Strength sends the percentage of the puppet’s walking speed the puppet is moving at, minus the running strength.

This means as you go faster you’ll approach 1 as the speed nears the walking speed. But if the puppet has a running speed greater than the walking speed, it will go back down to zero as it approaches the running speed.

Running Strength sends the percentage of the puppet’s running speed the puppet is moving at.

If the run is enabled, the puppet transitions between the base settings to running-keyframed settings based on the magnitude of the puppet interface’s walk input between 0.95 and 1.

These settings control the speed of the puppet based on the magnitude of the “walk” input on a corresponding puppet interface (I will refer to this as the “magnitude”). By default, that input is connected to the left stick on the controller that is possessing the puppet.

So if you push the left stick all the way to the outer edge on the controller, the magnitude is 1. If you let it stay in the centre, it is 0.

While moving, the maximum speed of the puppet is whichever is greater out of the walk and run speeds. This speed is modulated by the magnitude.

For example, at 0.97 magnitude it moves at 0.97 of its run speed. And at 0.5 magnitude it moves at half of the run speed. If the run speed is 10 m/s and the magnitude is at 0.5, the puppet will move at half of 10 m/s, which is 5 m/s.

While moving slower or equal to the set walk speed, the walk settings will be in effect. From above walk speed to the run speed, the settings will transition to the run settings. If the run speed is equal to or less than walk speed, the running settings will not come into effect.

For example, say the walk speed is 5 m/s, and the run speed is 15 m/s. The setting for “arm flail” is set to 0 for walking, and 100% for running. While the speed of the puppet is 10 m/s—halfway between its walk and run speeds—the arm flail will be at 50%—halfway between the walking arm flail and the running arm flail.
Note that in reality, this is most likely based on the magnitude value, and uses the ratio between walk and run speeds to figure out the transition. The explanation is still accurate, as the puppet speed and walk magnitude values are strongly linked.

The puppet interface’s walk/running strength outputs are also strongly linked to how this works internally.

# On Ground

Sends 1 if the puppet is standing on a collidable object. Sends 0 if the puppet’s feet are in the air. Sends something in between while walking.

# Left Heel Strike, Right Heel Strike, Foot Impact

Sends a signal for how close the puppet’s left heel, right heel, or both is to a surface the puppet can collide with.

# Outputs Page 2

# Velocity

The speed the puppet is moving, using the “local space” orientation.

# Acceleration, Deceleration

The acceleration and deceleration of the puppet.

# Lean Speed

The velocity of the puppet’s lean.

# Upper Body Movement

The velocity of the puppet’s upper body movement.

# Lower Body Movement

The velocity of the puppet’s lower body movement.

# Foot Scrape Amount

When the puppet has skateyness, sends a signal representing how much the feet are sliding across the surface.

# Jump Ascent, Jump Peak, Jump Descent

Sends values while the puppet is not on the ground, based on its upward velocity.

  • Ascent: While it has positive velocity (moving up), sends 1. As the velocity decreases, sends a lower value.
  • Peak: The closer the velocity is to 0, the closer the sent value is to 1.
  • Descent: While it has negative velocity (moving down), sends 1. As the velocity increases to 0, sends a lower value.

# Sliding

Sends a signal while the puppet is sliding on a slope that is steeper than it can walk on.