[v0.1.3] BloodFX — Part-based blood for Roblox

GitHub | Wally | Playground

Hey everyone!
This is my first topic here, so any feedback would be appreciated.

About

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.

Showcase

Example

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 impact
  • Burst — larger, wider impact
  • Drip — slow downward dripping
  • Jet — tight high-pressure stream
  • Fountain — 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 through
  • BloodAbsorb — drops disappear without leaving a mark
  • BloodAttach — 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.

More about

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.

Links

BloodFX.rbxm (20.1 KB)
Uncopylocked place
GitHub
Wally


Updates

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
  • PoolSize defaults to MaxDrops + 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; BloodAttach is now only for anchored parts that scripts move
  • DropMultiplier scales the drops of every spray, 0.5 on phones by default
  • Lighter defaults on phones
  • BloodFX.debugger reports a part pool that runs out and drop or mark limits being hit
  • PoolSize can change while the game runs
  • Landing on and cleaning up parts covered in blood is much faster
  • Now on Wally: ch1kz/bloodfx
31 Likes

This is gross, I love it! Are there any limitations, and how does it perform on mobile devices?

4 Likes

Gonna test it on a few devices tomorrow. We can probably detect the device type and adjust the settings for it. Like fewer particles and shorter lifetime on mobile

1 Like

Finally! Didn’t like having to use ediblemesh for the other blood module on devforum.
By the way, I checked config on GitHub by the way and found out about the BloodAttach parameter. Why wasn’t it the other way around, where by default unanchored parts have blood attached to them unless specified by tags? Personally, I think it would be very tedious to add tags to every unanchored part.

1 Like

Tags are mainly there for optimization. I assumed most maps have more static objects than dynamic ones. Automatically tracking every unanchored object and adding/removing tags would be less controllable and add extra overhead. I’ll try to find a compromise to make tagging easier, especially for people who don’t care as much about optimization.

1 Like

BloodFX 0.1.1 is out, and most of it came from this thread. Thanks for the feedback!

Why wasn’t it the other way around, where by default unanchored parts have blood attached to them unless specified by tags? Personally, I think it would be very tedious to add tags to every unanchored part.

Fair point, and now it is. Blood sticks on its own to anything physics can move: vehicles, props, doors on hinges, ragdolls, characters. BloodAttach is only needed for anchored parts that a script moves, like a lift or a tweened door.

What’s new

  • Blood sticks to unanchored parts on its own (AutoAttach turns it off)
  • DropMultiplier scales the drops of every spray: at 0.5, a spray of 10 throws 5
  • Lighter defaults on phones, including DropMultiplier at 0.5
  • BloodFX.debugger tells you when the part pool runs dry or MaxDrops / MaxMarks push blood out
  • PoolSize can change while the game runs
  • On Wally: BloodFX = "ch1kz/bloodfx@0.1.1"

Why not weld every mark?

I measured it first. A welded mark costs nothing while it rests, but three to six times more to create and resize than an anchored one: 130-420 us against 40-70 us to create. Most blood lands on the map, which never moves, so welding it would only make every splash more expensive. That’s why only parts that can move get welded marks, and the engine already knows which ones those are (BasePart:IsGrounded()).

The same tests found two slowdowns with welded marks, both fixed: finding the pool a drop joins no longer scans every mark on the part (314 us → 1.5 us with 1000 marks), and destroying a part with 2000 welded marks went from about 200 ms to 120 ms.

Upgrading

  • To keep the old behaviour, set AutoAttach = false
  • Config.luau has three new settings (Debug, AutoAttach, DropMultiplier), so take the new file and copy your values over; an old one breaks sprays
2 Likes

BloodFX 0.1.3 is out.

What’s new

  • Blood is drawn with a 96-triangle mesh instead of the engine’s 378-triangle sphere. It’s a public asset that loads by itself; until it arrives, or if it can’t, blood keeps the sphere
  • BloodFX’s work has its own labels in the MicroProfiler, so typing BloodFX into the filter shows what it costs in your game
  • PoolSize now defaults to MaxDrops + MaxMarks (1320, 660 on phones), and a pool that size never has to make parts on the spot
  • In the playground, F switches blood off and on

What it costs

I profiled the playground, which bleeds nonstop from five stations, on a weak laptop (Ryzen 5 3500U with built-in Vega 8 graphics), with blood on and off. Blood adds 1.6 ms of GPU time a frame at graphics level 2, where it stays at 60 FPS either way, and 3.2 ms at level 9, where it goes from 42 to 37 FPS. The mesh barely moved that laptop’s frame rate, because its GPU spends the frame lighting every pixel, not drawing triangles.

Upgrading

  • Config.luau has a new setting, Mesh, so take the new file and copy your values over; with the old one, blood stays the engine’s sphere
  • With Wally: BloodFX = "ch1kz/bloodfx@0.1.3"
2 Likes

Hey, we plan on using this for our project. I’m the scripter, and I need some information:

  • Is it possible to put realistic textures on those parts a bit like BloodEngine before?

I’m currently not home and can’t look into how this is made.

2 Likes

Not yet, but it’s planned for 0.2.0: custom looks for drops and pools, including pools drawn with textures picked at random from your own list. The update is planned for this weekend

2 Likes

will you benchmark between the other resources on here

does this include full pbr textures or colormap only

2 Likes

a pretty weird way of saying you like something

2 Likes

Any update on that?
We planned on using this but we need it to be editable

1 Like