ArrBrants’ Custom Splash Texts

Custom Splash

A mod that replaces or extends the yellow splash text on the Minecraft
title screen. Configure it with a JSON file or from code, add colours,
gradients, rainbows, placeholders and conditions — all without touching the
game files.

• Fabric, Forge and NeoForge, no other mods required.
• Fabric: Minecraft 1.14 through 26.3 — every stable release, 48 versions.
• Forge: Minecraft 1.16.1 through 1.20.6 — every release with a Forge build, 20 versions.
• NeoForge: Minecraft 1.20.5 through 26.3 — 18 versions, including the 26.x line.

Minecraft 1.16.0 and 1.17.0 have no Forge build and stay Fabric-only; 1.20.5 is
Fabric + NeoForge (Forge never shipped for it).

Client-side only; nothing changes in multiplayer.

Installation

Drop the JAR for your Minecraft version into mods/. On first launch the mod
creates config/customsplash.json. Until you edit it the title screen shows
Check your custom splash config file to customize!.

Forge downloads use the jars with -forge- in the filename, NeoForge downloads
the -neoforge- jars and Fabric downloads use the plain
customsplash-<mc>-… jars.

Upgrading from 1.x

Version 2.0.0 drops the hyphen from the mod id: NeoForge rejects custom-splash
and Forge 1.17 and newer derive an invalid Java module name from it, so before
this release the mod could not load on NeoForge at all or on Forge 1.17–1.19.4.
Two paths have to move with the id:

• rename config/custom-splash.json to config/customsplash.json — the file format is unchanged, so its contents need no edits;
• if you ship a resource pack, move its assets/custom-splash/splashes.txt (or splashes.json) to assets/customsplash/.

Nothing else about the config format or the SplashRegistry API changed.

Configuration

{
  "splashes": [
    { "text": "Check your custom splash config file to customize!" },
    { "text": "Hello, {player}!", "weight": 5, "color": "#FFAA00" },
    { "text": "Rainbow time", "color": "rainbow:25" },
    { "text": "Enjoy the weekend!", "conditions": { "weekend": true } },
    { "text": "Late night coding", "conditions": { "time": "night", "chance": 0.5 } },
    { "text": "You run Fabric!", "conditions": { "mods": ["fabric"] } }
  ]
}

• text — the splash text. Placeholders are replaced when the splash is drawn; unknown tokens are left untouched.
• weight — relative chance, default 1. Higher shows more often.
• color — a solid colour, a gradient or a rainbow, see below.
• conditions — every listed condition must match:
• time: day or night
• date: MM-DD or MM-DD..MM-DD (ranges may wrap across new year)
• weekend: true / false
• player: list of usernames
• mods: list of required mod ids
• chance: 0.0 – 1.0 random chance

Entries from the config file, from enabled resource packs and from
SplashRegistry.add(...) are all combined. When nothing matches, the vanilla
splash is used.

Placeholders

| Placeholder | Expands to |
| — | — |
| {player}, {username} | your username, or player when unknown |
| {date} | today as yyyy-MM-dd |
| {time} | the current time as HH:mm |
| {mc_version}, {mc}, {version} | the running Minecraft version |
| {mods}, {mods_count} | the number of loaded mods |

Placeholders are expanded once, when the splash is picked, so {time} is the
moment the title screen renders rather than a live clock. Placeholders that
cannot be resolved stay literal instead of showing a blank space.

Colours

| Value | Meaning |
| — | — |
| #RRGGBB | a single colour for the whole text |
| #RRGGBB,#RRGGBB | a gradient spread across the characters |
| #RRGGBB,#RRGGBB,… | a gradient with more than two stops |
| gradient:#RRGGBB,… | the same, spelled explicitly |
| rainbow | a hue cycle, 15° per character |
| rainbow:45 | a hue cycle with a custom degrees-per-character |

Anything that does not parse is ignored and falls back to the vanilla yellow.
A gradient is sampled per character, so each character gets its own
interpolated value and the first and last characters always match the stops
exactly.

{
  "splashes": [
    { "text": "Solid!", "color": "#FFAA00" },
    { "text": "Gradient!", "color": "#FF0000,#00FF00" },
    { "text": "Rainbow!", "color": "rainbow:25" }
  ]
}

On versions before 1.20, where the splash is a plain string that cannot carry
per-character styling, a gradient is approximated by prefixing each character
with the nearest legacy § code, and a solid #RRGGBB becomes a single §
code.

Resource packs

A resource pack can add splash texts by providing
assets/customsplash/splashes.txt. Each non-empty line becomes a splash text
and lines starting with # are ignored. Enabled packs are re-read
automatically, and SplashRegistry.reload() forces an immediate refresh.

For mod developers

Call SplashRegistry.add(String) during mod initialization (or any time
before the title screen renders):

import dev.arrbrants.customsplash.SplashRegistry;

public class MyMod implements ModInitializer {
    @Override
    public void onInitialize() {
        SplashRegistry.add("Hello! Fabric!");
        SplashRegistry.add("Powered by Mixin", 3); // weight 3
    }
}

The API also exposes remove(String), clear(), list(), count(), and
reload() (re-reads the config file and enabled resource packs). pick()
returns the chosen text and pickEntry() returns it together with its colour.

For Forge mods, register splashes during mod construction:

import dev.arrbrants.customsplash.SplashRegistry;

@Mod("mymod")
public class MyMod {
    public MyMod() {
        SplashRegistry.add("Hello! Forge!");
    }
}

NeoForge mods use the injected mod event bus:

import dev.arrbrants.customsplash.SplashRegistry;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.fml.common.Mod;

@Mod("mymod")
public class MyMod {
    public MyMod(IEventBus modEventBus) {
        SplashRegistry.add("Hello! NeoForge!");
    }
}

The SplashRegistry API is identical on all loaders.