
Shared beam effects for WePlay mods: wandering energy streams, spiraling helix strands, branching lightning with moods, impact sparks and looping sound.
For players
You probably got this because another mod needs it, such as WePlay: Personal Tesla Defense Equipment or WePlay: Phase Disruptor. There's nothing to set up: it adds no items, recipes or research, and does nothing on its own.
Want a sneak peek? Type /beamlib-demo proton while hovering over something to fire a preview beam at it. Try wander, helix and lightning too, and off to clear it.
For modders
Beams in Factorio are always drawn as straight strips. This library draws beams that bend: it builds a path, then draws it with glowing sprites that update in place every tick, or with short-lived beam pieces that re-roll, so beams can wander, coil, crackle and follow moving targets.
Features
- Path shapes: straight, jagged lightning corners, bowed arcs (random or fixed bows), and smooth splines through any set of points.
- Lightning bolts (new in 0.16.0): bolts that keep their shape relative to their ends, twitch between redraws instead of re-rolling, grow dead-end branches with sub-branches, and switch between frantic, normal and calm moods for irregular timing and flicker. Storage-safe. This is the engine behind the Tesla Defense Equipment.
- Wandering streams: waypoints that sway out of sync like a hose under pressure, pinned at the muzzle, with a tip that circles the target. Optional lanes let several streams fan out without crossing.
- Helix strands: any number of strands coiling around any path, spinning over time, with depth shading so they read as 3D from above, and solid front / glowing back layers that wrap around the beam.
- Pulses and surges: bright bands and big unstable beads that travel down the beam, swell it, bend it and land with a flare.
- Impact sparks: glowing streaks that burst from the tip, arc up, fall with gravity and bounce.
- Sound: a start sound, overlapping loop chunks for a seamless hum, and a stop sound that hands off cleanly from the last chunk.
- Grow-in: beams can shoot out from the source instead of popping in.
- Ready-made looks:
proton,helixandlightningpresets to start from. - Data stage helpers: Tesla-style visual beam pieces (with tint and animation-speed variants from the same sprite sheets, and a fading tip for dead ends) and an invisible damage beam for script-drawn visuals.
Quick start
-- info.json: "dependencies": ["base >= 2.0", "WePlayBeamLib >= 0.16.0"]
local beamlib = require("__WePlayBeamLib__/beamlib")
local opts = beamlib.presets.proton()
opts.source, opts.source_offset = player.character, {0, -1.3}
opts.target = enemy
storage.beam = beamlib.beam.new(opts)
-- in your on_tick (every tick, or every 2nd tick):
beamlib.beam.update(storage.beam, game.tick)
-- when you're done:
beamlib.beam.destroy(storage.beam)
Everything runs inside your own mod: your beams, your storage, your on_tick. Beams and bolts are plain tables, so they save with the game. The library has no runtime state of its own.
Performance
Built to stay light. A beam only creates render objects for its pieces and only writes the properties that actually change each update. Long beams can be capped to a fixed number of pieces, helix strands to a fixed number of samples, and beams can update every other tick with sparks catching up on the skipped ticks. Tints are applied when drawing, so colour variants cost no extra graphics memory.
Measured in the mods using it:
| Mod | Situation | Script time per tick |
|---|---|---|
| Phase Disruptor | eight streams over a biter base | ~0.3–0.5 ms |
| Tesla Defense Equipment | 15 units in a populated biter base, Quality | ~0.4–0.5 ms typical, ~1 ms peak |
| Tesla Defense Equipment | same, Performance | ~0.2 ms |
Full documentation
Every option, function and preset is documented in the README on GitHub: https://github.com/afewvowels/WePlayBeamLib
Versioning
New versions only add things; existing functions keep working the same way. Depend on a minimum version (WePlayBeamLib >= x.y.z) for the features you use.
Compatibility
- Made for Factorio 2.1.
- Space Age is optional.
Source
Released under the Unlicense: https://github.com/afewvowels/WePlayBeamLib
Mods using it
- WePlay: Personal Tesla Defense Equipment: armor equipment that zaps nearby enemies with wild, branching chain lightning in layered colours.
- WePlay: Phase Disruptor: armor equipment that locks wild, wandering energy streams onto nearby enemies. Just don't cross the streams.
See all my mods on my mod portal page.