GitHub | Wally | Playground
Hey everyone!
This is my first topic here, so any feedback would be appreciated.
BloodFX is a blood effect module for Roblox. Drops fly under gravity and splash wherever they land, leaving stains stretched in the direction they came from. Stains that land on each other merge into pools that spread across floors, stay smaller on walls and drip from ceilings. It’s all built from regular parts, so there are no textures or other assets to upload.
It comes with part pooling, runtime configuration, customizable presets, surface pooling/merging, dripping from ceilings and overhangs, emitters, blood that sticks to moving parts, lighter defaults on phones, a debugger you can listen to, and a bunch of other stuff under the hood.
The goal was to keep it lightweight, easy to drop into a project, and simple to tweak without having to dig through the internals.
Here’s a basic example, a LocalScript where clicking somewhere sprays 10 blood drops at the surface:
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local UserInputService = game:GetService("UserInputService")
local BloodFX = require(ReplicatedStorage:WaitForChild("BloodFX"))
local player = Players.LocalPlayer
local clickParams = RaycastParams.new()
clickParams.FilterType = Enum.RaycastFilterType.Exclude
UserInputService.InputBegan:Connect(function(input: InputObject, processed: boolean)
if processed or input.UserInputType ~= Enum.UserInputType.MouseButton1 then return end
local ray = workspace.CurrentCamera:ScreenPointToRay(input.Position.X, input.Position.Y)
clickParams.FilterDescendantsInstances = { player.Character }
local hit = workspace:Raycast(ray.Origin, ray.Direction * 500, clickParams)
if hit then
BloodFX.spray(hit.Position + hit.Normal * 0.25, hit.Normal, "Hit", 10) -- create 10 drops per click
end
end)
There’s quite a bit more to the module than this, but I tried to keep the public API small and straightforward.
If you want the full breakdown, check out the README on GitHub. Otherwise, here’s the TL;DR:
Quick Start, API & Configuration
Getting Started
With Wally, add BloodFX to your wally.toml and run wally install:
[dependencies]
BloodFX = "ch1kz/bloodfx@0.1.1"
Without Wally, grab the BloodFX module from the GitHub repo or the uncopylocked place and put it in ReplicatedStorage.
BloodFX is a local visual effect, so you normally want to require it from a LocalScript:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local BloodFX = require(ReplicatedStorage:WaitForChild("BloodFX"))
With Wally the module sits in ReplicatedStorage.Packages.BloodFX instead.
The module initializes itself on the first require.
Basic API
Spray
BloodFX.spray(position, direction)
BloodFX.spray(position, direction, "Hit")
BloodFX.spray(position, direction, "Hit", 10)
BloodFX.spray(position, direction, "Burst", {
count = NumberRange.new(12, 20),
})
spray() fires a cone of blood drops from a position in a given direction.
The third argument can be a preset name or your own preset table. The fourth argument lets you override individual preset values for that call, or you can pass a number there to set just the drop count.
Marks
BloodFX.mark(position, normal, radius)
Places a blood mark directly onto a surface without spawning a flying drop first.
Emitters
local wound = BloodFX.emitter(character.UpperTorso, "Fountain", {
beats = 2,
})
wound:destroy()
Emitters are continuous blood sources and can use a PVInstance, Attachment, or CFrame as their origin.
Emitter properties can also be changed while they’re running, including enabled, strength, and preset-specific values. A preset with its own update logic may rewrite some of them every frame: Fountain sets strength from its beats and swing, so change those instead.
Utility
BloodFX.clear()
BloodFX.fade()
BloodFX.freeze()
BloodFX.unfreeze()
print(BloodFX.isFrozen())
print(BloodFX.stats())
clear() removes everything immediately, while fade() makes every existing mark fade out right away instead of waiting for its lifetime to run out.
freeze() clears the current effect and pauses new blood/emitter output until unfreeze() is called.
stats() gives you the current drop, mark and emitter counts, plus how many parts the pool holds and how many of them are spare.
Debugger
BloodFX.debugger:Connect(function(event)
warn("[BloodFX]", event.kind, event.limit)
end)
The debugger tells you when the part pool runs out of spare parts (PoolExpanded) and when MaxDrops or MaxMarks push out a drop or a mark (DropLimit, MarkLimit). It doesn’t print anything by itself, so what to do with it is up to you. Debug = false in the Config silences it for a release.
Presets
The built-in presets are:
Hit— regular impactBurst— larger, wider impactDrip— slow downward drippingJet— tight high-pressure streamFountain— pulsing arterial-style stream
All presets live in:
BloodFX/Presets.luau
Adding your own preset is just adding another entry to that table.
Presets control things like drop count, speed, spread, radius, emitter direction/rate, and can even contain custom update logic.
Configuration
All default settings live in:
BloodFX/Config.luau
This includes performance limits, the part pool, color/material, drop physics, mark lifetime and sizing, merging/pooling behavior, ceiling drips, blood on moving parts, the debugger, and CollectionService tags.
Phones (a touch screen and no keyboard) get lighter defaults on their own: fewer drops and marks at once, marks that fade sooner, and DropMultiplier at 0.5, so every spray throws half as many drops as the script asks for.
Changing Settings at Runtime
Runtime configuration is enabled by default.
You can change supported settings through the API:
BloodFX.set("Gravity", 80)
BloodFX.set("MaxMarks", 600)
BloodFX.set("Color", Color3.fromRGB(100, 0, 0))
print(BloodFX.get("Gravity"))
You can also tweak them manually while the game is running.
After BloodFX initializes, go to:
Workspace
└── BloodFX
└── Config
The Config object exposes runtime settings as Attributes, so you can edit them directly in Studio and see the changes immediately.
The folder belongs to whichever side required the module, normally the client, so during a playtest look for it in the client view. If the server requires BloodFX too, it gets a folder of its own, and editing that one from the client changes nothing.
Only DynamicSettings and the CollectionService tag names are static; change those in Config.luau before the module initializes. Everything else, PoolSize included, can change while the game runs.
Tags
BloodFX also supports three CollectionService tags:
BloodIgnore— drops pass straight throughBloodAbsorb— drops disappear without leaving a markBloodAttach— marks stick to the hit part and move with it
Blood already sticks on its own to anything physics can move (unanchored parts: vehicles, props, doors on hinges, ragdolls), so BloodAttach is only needed for anchored parts that scripts move, like lifts or tweened doors.
Tags can be applied to individual parts or entire models/folders.
If you run into a bug, have an idea, or want to contribute, drop a reply in this thread or open an issue / pull request on GitHub.
Contributions are welcome.
BloodFX.rbxm (20.1 KB)
Uncopylocked place
GitHub
Wally
0.1.3
- Blood is drawn with a 96-triangle mesh instead of the engine’s 378-triangle sphere
- BloodFX’s work has its own labels in the MicroProfiler
PoolSizedefaults toMaxDrops+MaxMarks(1320, 660 on phones), and a pool that size never grows- Playground: F switches blood off and on
0.1.1
- Blood sticks to unanchored parts on its own, no tags needed;
BloodAttachis now only for anchored parts that scripts move DropMultiplierscales the drops of every spray, 0.5 on phones by default- Lighter defaults on phones
BloodFX.debuggerreports a part pool that runs out and drop or mark limits being hitPoolSizecan change while the game runs- Landing on and cleaning up parts covered in blood is much faster
- Now on Wally:
ch1kz/bloodfx
