Distortion

A Distortion emitter bends the picture of the 3D world for a moment, as if seen through moving glass. It makes a shockwave ring, a heat shimmer, or a lens that bulges or pinches. It is made from an ordinary Part with Transform as Distortion, and the Part becomes an invisible marker for the centre of the bend.

What it makes possible:

A shockwave ring from an explosion. Field Ripple, Wavelength 0.15, Speed 8, Lifetime 1, an Amplitude graph from 1 to 0. The explosion’s On Emit event fires it.
A heat shimmer over a fire. Field Noise, Mode Animate, Loop on, Amplitude 0.15, Noise Scale 6, Direction 90, Falloff 60, Transparency 0.6.
A view that wobbles as under water. Field Wave, Epicenter ScreenCenter, Mode Animate, Loop on, Wavelength 0.5, Speed 2.
A pull toward an object. Field Pinch, Lens Radius 0.3, an Amplitude graph that rises from 0 and returns to 0.

Exercise 15 makes the shockwave ring step by step.

At a glance


Made from	An ordinary Part, with ▾ ▸ Transform as Distortion
One particle is	One running field of bending. Nothing is created in the workspace.
Emit count starts at	1
Modes	Emit and Animate
Sections	Emission, Field, Screen, Events, Advanced
Not present	Spawn, Motion and Link. There is no Linger row and no Emit Into row.

Distortion is meant for short bursts.

Transform

Select an ordinary Part that has not been transformed. Press ▾ beside Transform, then click Transform as Distortion.

The Part turns invisible.
Meshes and decals inside the Part are removed.
The Part’s collision is left as it was.
Nothing of the Part’s look is kept. The Part only marks a place.

The Emit count starts at 1. A new Distortion plays at the first press of the Emit button.

Units on screen

Distances on screen use one unit: 1 is about one screen height. Distances across the screen use the same unit. A ring or a lens stays round on a screen of any shape.

Angles are in degrees. 0 points right, 90 up, 180 left and 270 down.

Emission

Row	Kind	Starts at	Unit	What it does
Mode	List	`Emit`		Emit or Animate. See Emit against Animate.
Loop	Switch	Off		Shown in Animate mode. Repeats the effect until switched off. Switching it on starts the effect at once.
Enabled	Switch	Off		Shown in Emit mode. Starts distortions at the Rate until switched off.
Rate	Number	10	Distortions per second	Shown in Emit mode. How many start each second while Enabled is on, or during a Duration.
Lifetime	Two numbers	0.5	Seconds	How long each distortion lasts. Each picks a value between the two.
Timescale	Graph	1		The speed of the distortion’s own clock. It slows, pauses or reverses the moving field.

The Emit, Delay and Duration boxes on the HUD fire a Distortion as they fire any other emitter. Emission and the HUD describes the shared rows in full.

Field

Row	Kind	Starts at	Unit	What it does
Field	List	`Ripple`		The shape of the bend. See The five Field kinds.
Amplitude	Graph	0.5		How strongly the picture is bent, over the life of the distortion.
Wavelength	Number	1.5	Screen heights	For a Ripple, the thickness of the ring. For a Wave, the distance between crests.
Speed	Number	3		How fast a ring grows, a Wave travels or a Noise drifts.
Direction	Number	0	Degrees	Which way a Wave travels or a Noise drifts.
Noise Scale	Number	2	Blobs per screen height	The grain of the shimmer. A higher value is finer.
Lens Radius	Number	1.5	Screen heights	The radius of the lens.

Rows that the chosen Field does not use are hidden. The table below lists the rows each Field uses. With Distortions of different Fields selected, every row shows.

The five Field kinds

Field	What is seen	Rows it uses	Notes
`Ripple`	One ring of bending that spreads out from the centre.	Amplitude, Wavelength, Speed	The ring starts at the centre and its radius grows with time.
`Wave`	Straight waves that cross the whole screen.	Amplitude, Wavelength, Speed, Direction	A Wave has no centre.
`Noise`	An uneven shimmer that drifts across the screen.	Amplitude, Noise Scale, Speed, Direction	Each emit gets its own random pattern. Two that overlap do not line up.
`Bulge`	A still lens that pushes the picture outward.	Amplitude, Lens Radius	It does not move by itself. Give it motion with the Amplitude graph.
`Pinch`	The same lens, pulling inward.	Amplitude, Lens Radius

Amplitude

The bend looks the same at any field of view and any screen resolution. A keypoint below 0 is kept as 0.

Past a certain strength the bend stops growing, and its peaks flatten. Amplitude and Strength together decide when that happens.

Wavelength

A new Ripple has Wavelength 1.5 and Lifetime 0.5. That ring is wider than the screen and hardly moves, so it shows as a broad swell. A shockwave ring needs a Wavelength of 0.1 to 0.3, a higher Speed and a longer Lifetime.

For a Wave, a Wavelength of 0.25 puts four crests down the height of the screen.

A Wavelength below 0.02 is run as 0.02.

Speed

For a Ripple, the radius of the ring grows by Speed times 0.1 screen heights each second.

Speed	The ring grows	From the middle of the screen to the top edge
3	0.3 screen heights a second	About 1.7 seconds
8	0.8 screen heights a second	About 0.6 seconds

Timescale multiplies Speed. A Speed below 0 sends a Wave or a Noise the other way.

Noise Scale and Lens Radius

Noise Scale is about the number of blobs in one screen height. A value below 0.05 is run as 0.05.

Lens Radius starts at 1.5, which is larger than the screen. A radius of 0.2 to 0.4 gives a lens that is seen as a lens. A value below 0.02 is run as 0.02.

Screen

Row	Kind	Starts at	Unit	What it does
Epicenter	List	`WorldPoint`		Where the bend is centred: `WorldPoint` or `ScreenCenter`.
Falloff	Number	0	Studs	The distance from the camera to the Part at which the effect has faded to nothing. At 0 there is no fade.
Strength	Number	1	Multiplier	A plain multiplier on Amplitude.
Transparency	Graph	A graph from 0.3 to 1	0 to 1	How present the bend is, over the life of the distortion. At 1 the effect cannot be seen.
Amplify	Number	0		An experimental extra-strong mode. 0 is off. See Amplify.
Allow Overdrive	Switch	Off		Gives permission for Amplify.
Resolution	Number	24		How fine the bend is across the screen. A higher value is smoother and costs more.

Epicenter

Epicenter	The centre of the bend
`WorldPoint`	The place where the Part appears on screen. It follows the Part and the camera in every frame.
`ScreenCenter`	The middle of the screen.

With WorldPoint:

A Distortion nested in another emitter is centred on the parent particle.
A Distortion fired by an event at a position keeps that position for its whole life.
If the point is off screen, the centre is off screen. A ring still sweeps into view.
If the point passes behind the camera, the effect fades out. It stays off while the point is behind the camera.

The last rule also switches off a Wave and a Noise, which have no centre to see. For a Wave or a Noise that must not depend on the Part, set Epicenter to ScreenCenter.

Falloff

Falloff works as it does for a Camera Shake. The effect is full at the Part and gone at the Falloff distance. With Falloff at 100, the effect has half its strength at 50 studs.

Falloff applies with both Epicenter settings. With ScreenCenter it still measures the distance from the camera to the Part.

A value of 0 or less gives no fade with distance. The empty box reads studs, 0=global.

Strength

An Amplitude graph at 0.5 with Strength 2 bends as hard as an Amplitude of 1. At a Strength of 0 nothing bends.

Transparency

The starting graph runs from 0.3 to 1. It ends at 1 so that the effect ends without a jump. A keypoint below 0 is kept as 0.

Keep the graph between 0 and 1. A value above 1 asks for the extra-strong mode described under Amplify.

Amplify

Amplify is an experimental extra-strong mode. It relies on engine behaviour that may change. If it stops working, the effect falls back to normal strength.

Allow Overdrive must be on.
Amplify is used only when every distortion running at that moment has Allow Overdrive on. One distortion without it switches Amplify off for all.
Any value above 0 is run as at least 4 and at most 10. The empty box reads 4-10 overdrive, 0=off.
When several distortions ask for Amplify, the highest value is used.

Resolution

A value below 24 acts as 24. The highest value is 96.

All running distortions share one Resolution: the highest that any of them asks for. Once raised, it is not lowered again while the plugin stays on. One Distortion with a high Resolution raises the cost of every later one.

Several at once

What	How running distortions combine
The bend	Added together.
Transparency	The lowest value among them is used for all.
Resolution	The highest value among them is used for all.
Amplify	The highest value, and only if every one has Allow Overdrive on.

At most 64 distortions run at once. Extra ones are dropped, and the Output window reads, once:

[Part-Icles] Distortion: more than 64 simultaneous effects; extras dropped this frame

An Emit count above 1 stacks distortions that start together. For Ripple, Wave, Bulge and Pinch they are identical, so the result is the same shape, stronger. Noise differs from one to the next.

Emit against Animate

	Emit	Animate
What plays	A new distortion for each emit.	One distortion for the emitter.
Emit count and Rate	Used.	Not used. The Rate row is hidden.
Fired again while playing	Another distortion is added.	The press is ignored until the distortion ends.
Loop	Not shown.	Off: the distortion plays once and ends. On: it repeats until Loop is switched off.

With Loop on, every row is read again at each pass. A Noise and a Wave carry on smoothly from one pass to the next. A Ripple, a Bulge and a Pinch start again.

In the editor

Pressing Emit shows the effect in the Studio viewport. Only you see it, and it is not saved with the place.

Motion Preview draws nothing for a Distortion.

In a game

A distortion is seen by one player: the one whose machine fires it. For every player to see it, each player’s machine must fire the emitter. See Firing an effect.

Fired from a server script, a Distortion does nothing. The Output window reads, once:

[Part-Icles] Distortion ignored on the server (no screen).

Distortions are shown by one running copy of Part-Icles at a time. A second copy shows none until the first stops. The Output window reads:

[Part-Icles] Distortion: another Part-Icles engine owns the screen canvas; this engine's distortions are disabled

Quality

In the simpler version, Bulge and Pinch look the same. Resolution and Amplify have no effect.

Events

The Events section holds On Emit, On Death and On Destruction. There is no On Hit. See Events.

In an event script, payload.Particle is nil. payload.SetColor and payload.SetTransparency do nothing. See The event script and its payload.

A Distortion can be nested in a Part or Model emitter. It then fires once for each parent particle. See Nesting.

Emitters placed inside a Distortion are never fired.

Advanced

Row	Kind	Starts at	What it does
Anim. Steps	Number	100	How many times the Amplitude and Transparency graphs are read over one Lifetime. A value of 0 or less is run as 100.

The field itself moves in every frame. Only the two graphs are read in steps.

Advanced describes this row in full.

With the tools

Tool	Effect on a Distortion
Size	Multiplies Falloff.
Time	Multiplies Rate and Speed. Divides Lifetime.
Randomize	Leaves Field, Epicenter, Amplify, Allow Overdrive and Resolution as they are.

Size and Time and Randomize describe the tools.

Limits

Distortion is meant for short bursts.
It bends the picture of the 3D world. Screen UI is not bent, and that includes ImageLabel particles.
The bend fades to nothing in a band along the edges of the screen.
At most 64 distortions run at once.
A distortion is seen by one player. A server script cannot fire it.
No Linger row. A distortion ends when its Lifetime ends.
Emitters placed inside a Distortion are never fired.