WePlay: Beam Library


Shared beam effects for WePlay mods: wandering energy streams, spiraling helix strands, jagged lightning, impact sparks and looping sound, drawn with glowing sprites that bend and move every tick. Does nothing on its own; try /beamlib-demo for a preview.

Internal
3 hours ago
2.1
60
Owner:
afewvowels
Source:
https://github.com/afewvowels/WePlayBeamLib
Homepage:
N/A
License:
The Unlicense (Public Domain)
Created:
4 days ago
Latest Version:
0.17.0 (3 hours ago)
Factorio version:
2.1
Downloaded by:
60 users

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, helix and lightning presets 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

See all my mods on my mod portal page.