The Problem

Hytale has no concept of music-driven world state. Sound events play, the world does its thing, and the two are entirely decoupled. The goal of Pulse was to bridge that gap — to make the game world react to music in real time, with effects timed precisely to beats, onsets, section changes, and even individual words.

The constraint that shaped everything: Hytale’s server runs on the main game thread. Any heavy computation done at runtime would introduce lag. Audio analysis — spectral decomposition, onset detection, ML-based transcription — is expensive. It cannot happen live.

The solution is a two-stage pipeline:

[Offline]  Audio file → Python analyser → Beat map JSON
[Runtime]  Beat map JSON → Pulse event dispatcher → World effects

The hard work happens offline, once per song. Runtime is just reading timestamps from a file and dispatching events.

Stage 1 — The Python Analyser

The analyser (analyze.py) takes an audio file and produces a JSON beat map containing everything the plugin needs to drive effects. It uses librosa for audio analysis and optionally whisperx or whisper for lyric alignment.

Tempo Detection

Reliable tempo detection is harder than it sounds — especially for hip-hop and electronic music where the perceived BPM can be half or double the detected value. I implemented a voting system across five independent methods:

• Standard onset envelope tempo estimation
• Percussive component with hip-hop prior
• Low-frequency (kick drum) autocorrelation
• Fourier tempogram peak detection
• Standard beat_track fallback

Candidates are binned into a histogram and the median of the peak cluster is returned. A manual BPM override is also supported for cases where the voting system drifts.

def get_tempo_with_voting(y, sr, hop_length, y_percussive=None):
    candidates = []
    # ... five independent estimates ...
    hist, bin_edges = np.histogram(candidates, bins=np.arange(60, 180, 5))
    peak_bin = np.argmax(hist)
    bin_center = (bin_edges[peak_bin] + bin_edges[peak_bin + 1]) / 2
    near_peak = candidates[np.abs(candidates - bin_center) < 10]
    return float(np.median(near_peak))

Frequency-Separated Onset Detection

Rather than treating the audio as a single signal, the analyser separates it into frequency bands — bass (kick drum), mids (snare, melodic), highs (hi-hats, cymbals), and vocals — and detects onsets independently in each:

y_bass  = bandpass_filter(y_percussive, sr, 20, 150, hop_length)
y_mids  = bandpass_filter(y, sr, 500, 2000, hop_length)
y_highs = bandpass_filter(y, sr, 4000, 16000, hop_length)
y_vocals = bandpass_filter(y_harmonic, sr, 300, 3500, hop_length)

This means the plugin can drive different effects for different frequency events — bass onsets trigger ground-level effects, hi-hat onsets trigger rapid upper-register effects, vocal onsets trigger word-aligned effects.

Continuous Curves

Beyond discrete events, the beat map also contains continuous curves sampled at regular intervals:

• Energy curve — normalised RMS envelope, 50ms samples
• Spectral flux — rate of change in the frequency spectrum
• Pitch contour — normalised pitch (0–1) with direction (rising/falling/stable)
• Frequency bands — per-band energy (sub, bass, lowMid, mid, highMid, high) for equaliser-style effects

These enable smooth interpolation between states rather than sharp on/off transitions.

Section Detection & Structural Analysis

The analyser uses librosa.segment.agglomerative on combined MFCC and chroma features to find structural boundaries, then classifies each section:

features = np.vstack([
    librosa.util.normalize(mfcc, axis=1),
    librosa.util.normalize(chroma, axis=1)
])
bounds = librosa.segment.agglomerative(features, k=num_sections)

A recurrence matrix identifies which sections repeat — chorus sections appear multiple times and get flagged accordingly. Each section is classified as intro, verse, chorus, hook, bridge, buildup, drop, breakdown, or outro, with a mood label (energetic, aggressive, melancholic, peaceful, dark, happy, etc.) derived from energy, brightness, and tempo.

Lyric Alignment

If lyrics are provided — either as a file or fetched from the Genius API — the analyser uses WhisperX for forced alignment:

result = whisperx.align(
    result["segments"], model_a, metadata, audio, device,
    return_char_alignments=False
)

The key insight in the alignment system: we trust our lyrics for the text, but use the transcription for the timing. A fuzzy matching pass maps known correct words to their nearest transcribed timestamp, handling the minor errors Whisper inevitably makes. The result is word-level timestamps with 100% textual accuracy.

The analyser is compiled into a platform-specific binary (Windows/Mac/Linux) via PyInstaller and called from the plugin as a subprocess:

ProcessBuilder pb = new ProcessBuilder(
    getAnalyzerPath(),
    audioFile.getAbsolutePath(),
    outputFile.getAbsolutePath(),
    "--bpm", String.valueOf(bpm),
    "--song", songTitle,
    "--artist", artist
);

Stage 2 — The Hytale Plugin

The Beat Map

SongBeatMap is a flat POJO that mirrors the JSON output exactly:

public class SongBeatMap {
    public double bpm;
    public double duration;
    public String mood;
    public double[] beatTimestamps;
    public double[] downbeats;
    public double[] eighthNotes;
    public double[] sixteenthNotes;
    public Onset[] bass;
    public Onset[] mids;
    public Onset[] highs;
    public Section[] sections;
    public Buildup[] buildups;
    public Drop[] drops;
    public EnergySample[] energyCurve;
    public PitchSample[] pitchContour;
    public Word[] words;
    // ...
}

Gson deserialises the JSON into this structure once at song load. Runtime access is just array indexing.

The Event System

Each musical event type maps to a Hytale IEvent implementation:

public class PulseMainBeatEvent  extends PulseEvent implements IEvent<Void>
public class PulseDownbeatEvent  extends PulseEvent implements IEvent<Void>
public class PulseOnsetEvent     extends PulseEvent implements IEvent<Void>
public class PulseSectionEvent   extends PulseEvent implements IEvent<Void>
public class PulseSongStartEvent extends PulseEvent implements IEvent<Void>
public class PulseSongEndEvent   extends PulseEvent implements IEvent<Void>

All inherit from PulseEvent, which carries a SongContext record — BPM, average energy, duration, beats per bar, and mood — so every listener has full song context without needing to query a shared state object:

public record SongContext(
    double BPM,
    double averageEnergy,
    double duration,
    double beatsPerBar,
    String mood
) {}

The dispatcher reads the beat map’s timestamp arrays, schedules events ahead of time using HytaleServer.SCHEDULED_EXECUTOR, and fires them as the song progresses. All scheduling happens on a background thread — the main game thread only runs the actual world mutations triggered by the event listeners.

Visual Effects

PulseEffects implements the world-space effects. A few highlights:

Equaliser — a row of block columns that rise and fall in a sine wave pattern on each beat, timed with staggered delays for a ripple effect:

double wave = Math.sin(Math.PI * i / (barCount - 1));
final int height = 1 + (int)(wave * (maxHeight - 1));
final int staggerDelay = i * 20; // ripple left to right

Circular pillar wave — pillars arranged in a ring, rising sequentially around the circumference so the wave propagates spatially:

double angle = (2 * Math.PI / pillarCount) * i;
final int bx = (int)(center.x + Math.cos(angle) * distance);
final int bz = (int)(center.z + Math.sin(angle) * distance);

Bloom pulse — the post-processing bloom intensity is driven directly via UpdatePostFxSettings, allowing the screen to pulse with the beat without any world geometry changing:

UpdatePostFxSettings pulsePacket = new UpdatePostFxSettings(
    intensity, 8.0f, 4.0f, 0.25f, 0.3f
);
player.getPacketHandler().writePacket(pulsePacket, true);

Camera shake — on strong hits above a threshold, CameraShakeEffect is sent directly to the player’s packet handler:

if (intensity > 0.8f) {
    playerRef.getPacketHandler().writePacket(
        new CameraShakeEffect(1, intensity * 0.3f, AccumulationMode.Average), true
    );
}

Mood-mapped colours — section mood drives the colour palette for all effects:

private Color getMoodColor(String mood) {
    return switch (mood) {
        case "energetic"  -> Color.YELLOW;
        case "aggressive" -> Color.RED;
        case "melancholic"-> Color.BLUE;
        case "peaceful"   -> Color.CYAN;
        case "dark"       -> Color.MAGENTA;
        case "happy"      -> Color.PINK;
        default           -> Color.WHITE;
    };
}

The Spline

PulseSpline wraps Hytale’s IPath API to expose a getPositionAt(double t) method — given a normalised time value (0–1), it returns the corresponding world-space position along a designer-placed path. This is how effects are anchored to the world spatially: the progress of the song maps directly to position along a spline, so a four-minute song traverses the entire path exactly once:

public Vector3d getPositionAt(double t) {
    t = Math.max(0, Math.min(1, t));
    int segments = points.size() - 1;
    double scaledT = t * segments;
    int segment = Math.min((int) scaledT, segments - 1);
    double localT = scaledT - segment;
    // linear interpolation between adjacent waypoints
    ...
}

Architecture Summary

The two-stage design is the key architectural decision. Hytale servers handle real-time game state for many concurrent players — introducing a Python audio analysis pipeline into the hot path would be catastrophic. By doing all analysis offline and reducing runtime to scheduled event dispatch from a pre-computed data structure, Pulse adds zero measurable overhead to the server tick.

The event system mirrors Hytale’s own IEvent pattern, meaning Pulse effects integrate naturally with any other plugin listening to the same bus. A game designer could respond to PulseMainBeatEvent the same way they’d respond to any other server event — no special integration required.

View Repo

The Concept

The core loop is simple: mine, collect pets, upgrade, raid. Each layer feeds the next — mining surfaces pets and resources, pets power raid encounters, raids yield rare rewards that feed back into the economy. The design is deliberately inspired by idle tycoon and collection mechanics, adapted for a Minecraft server environment where the interaction model is spatial and real-time rather than menu-driven.

The constraint I worked to: every system should be readable to a new player in under a minute. Minecraft players have limited tolerance for UI complexity.

Pet Rarity System

Eight rarity tiers — COMMON through PRISMATIC — each with a weighted drop chance and a colour used consistently across all UI surfaces:

public enum PetRarity {
    COMMON(ChatColor.GRAY, "Common", 50.0),
    UNCOMMON(ChatColor.GREEN, "Uncommon", 30.0),
    RARE(ChatColor.BLUE, "Rare", 15.0),
    EPIC(ChatColor.DARK_PURPLE, "Epic", 4.0),
    LEGENDARY(ChatColor.GOLD, "Legendary", 0.8),
    MYTHICAL(ChatColor.RED, "Mythical", 0.15),
    CELESTIAL(ChatColor.AQUA, "Celestial", 0.04),
    PRISMATIC(ChatColor.LIGHT_PURPLE, "Prismatic", 0.01);
    ...
}

The drop chances sum to 100.0. Rolling a pet calls getRandomRarity(), which accumulates probability mass across tiers until the random value is exceeded — standard weighted random selection.

The more interesting variant is getRandomRarity(double luckMultiplier), which takes a luck value from the player’s equipped pet stats and scales the probability distribution toward higher tiers:

for (int i = 0; i < rarities.length; i++) {
    double tierBonus = 1.0 + (i * 0.2);
    adjustedChances[i] = rarities[i].getDropChance() * Math.pow(luckMultiplier, tierBonus);
    totalChance += adjustedChances[i];
}

Higher-tier rarities get a larger exponent applied to the luck multiplier — meaning luck has a compounding effect on rare drops rather than a flat shift. A lucky pet meaningfully changes your odds of finding a Prismatic without trivialising the rarity curve at the Common/Uncommon end.

Pet Architecture

Each Pet instance holds its own stat map, ability list, level, XP, evolution ID, mining power, and arena bonus. Stats are initialised from the pet’s type and rarity at construction, then scaled with level:

public int getRequiredXPForNextLevel() {
    return (int) (100 * Math.pow(level, 1.5));
}

The polynomial XP curve means early levels are fast and later levels slow down meaningfully — the same pattern used in most MMO progression systems. Level is capped at 100.

Type determines the pet’s role in the minigame loop:

• ATTACK — +2% arena bonus base, scales into raid damage
• MINING — +2 base mining power, surfaces more pets per session
• SUPPORT / TANK / SPEED — utility roles with distinct stat profiles

Each pet exposes getEffectiveMiningPower() and getEffectiveArenaBonus() — derived values that fold in the level bonus — so the rest of the codebase never has to re-derive these:

public int getEffectiveMiningPower() {
    return (int) (miningPower * (1 + (level - 1) * 0.05));
}

Pets are serialised and deserialised via saveToConfig / loadFromConfig using Bukkit’s ConfigurationSection API, keeping persistence straightforward without a database dependency at this scale.

PetTemplate

PetTemplate decouples the definition of a pet species from the instance of a player’s specific pet. Templates define the archetype — name, rarity, type, base stats, abilities, evolution chain — and createPet() stamps out a fresh Pet instance from the template. This is the standard Prototype pattern applied to game object instantiation.

The Raid System

Raids are the endgame cooperative loop. An ActiveRaid holds the live state of an in-progress encounter:

public class ActiveRaid {
    private final Set<UUID> participants = new HashSet<>();
    private final Map<UUID, Integer> participantDamage = new HashMap<>();
    private RaidState state = RaidState.WAITING;
    private RaidBoss boss;
    ...
}

RaidState progresses through WAITING → READY → IN_PROGRESS → COMPLETED / FAILED. The state machine is simple and explicit — no ambiguity about what a raid instance is doing at any point.

Damage tracking is per-participant, which enables a top damage leaderboard at completion:

public List<UUID> getTopDamageDealers(int count) {
    return participantDamage.entrySet().stream()
        .sorted(Map.Entry.comparingByValue(Comparator.reverseOrder()))
        .limit(count)
        .map(Map.Entry::getKey)
        .collect(Collectors.toList());
}

This feeds the reward distribution — top contributors receive better loot tiers, incentivising active participation over passive presence.

RaidBoss carries its own rarity — a boss’s rarity tier gates which pet eggs can drop as completion rewards, creating a direct link between the difficulty of the encounter and the quality of the loot pool.

Damage to the boss is clamped to current health so overkill is always handled gracefully:

public int takeDamage(int damage) {
    int actualDamage = Math.min(currentHealth, damage);
    currentHealth -= actualDamage;
    return actualDamage;
}

Mine Regions

Mines are defined as bounded world-space regions — MineRegion holds a min/max Location pair and exposes a contains(Location) check used to determine when a player is actively mining within a valid zone:

return location.getX() >= min.getX() && location.getX() <= max.getX() &&
       location.getY() >= min.getY() && location.getY() <= max.getY() &&
       location.getZ() >= min.getZ() && location.getZ() <= max.getZ();

Regions auto-reset on a 5-minute timer (needsReset() checks System.currentTimeMillis() against lastResetTime), keeping mines populated without manual intervention.

Trading

The Trade class supports bidirectional exchange of pets, items, coins, and gems — each tracked separately per player. Both parties must explicitly call setAccepted(true) before any transfer occurs. The TradeManager holds all active trades keyed by participant UUID, with a TradeRequest intermediary for the invitation flow before a trade session opens.

Pets are deep-copied via Pet.copy() before being placed into a trade — ensuring the original is never mutated until the trade settles. This prevents a race condition where a pet’s state changes between being offered and the trade completing.

View Repo

Why Rust, and Why From Scratch

Most Minecraft server development happens on top of Spigot or Paper — abstractions that handle the protocol layer entirely. You write plugins, respond to events, and never think about what’s happening on the wire. That’s the right approach for building games. But I wanted to understand the protocol at a level that Spigot doesn’t expose.

Rust was the natural choice. The Minecraft protocol is fundamentally a binary serialisation problem over a TCP stream — exactly the kind of problem Rust handles elegantly, with zero-cost abstractions, explicit memory ownership, and no garbage collector introducing latency. Writing a game server in a language that competes with C for raw throughput is the right call when you’re thinking about hundreds of thousands of concurrent connections.

The Minecraft Protocol

Before writing a line of code, I spent time with wiki.vg — the community-maintained Minecraft protocol documentation. The protocol has four states: Handshaking, Status, Login, and Play. Each state defines a set of packets, each with a specific format.

Packets are structured as:

[Length: VarInt] [Packet ID: VarInt] [Data: ...]

A VarInt is a variable-length integer encoding — the same format used in Protocol Buffers. Each byte uses 7 bits for data and 1 bit as a continuation flag. Small numbers take 1 byte, larger ones take up to 5.

Reading and writing VarInts correctly is the first thing you implement, and the first thing that breaks when you get it wrong.

pub fn read_varint(buf: &mut Cursor<&[u8]>) -> Result<i32> {
    let mut result = 0i32;
    let mut shift = 0;
    loop {
        let byte = buf.read_u8()?;
        result |= ((byte & 0x7F) as i32) << shift;
        if byte & 0x80 == 0 {
            break;
        }
        shift += 7;
        if shift >= 35 {
            return Err(anyhow!("VarInt too long"));
        }
    }
    Ok(result)
}

The Authentication Handshake

This is the part that separates a toy implementation from something real. Online mode Minecraft uses a three-step authentication process involving RSA encryption, AES stream cipher, and Mojang’s session server.

Step 1 — Encryption Request

The server generates an RSA key pair and sends the client a public key alongside a random 4-byte verify token:

let rsa = Rsa::generate(1024)?;
let public_key_der = rsa.public_key_to_der()?;

// Send Encryption Request packet
// [Public Key Length: VarInt] [Public Key: Bytes]
// [Verify Token Length: VarInt] [Verify Token: Bytes]

Step 2 — Encryption Response

The client responds with two values, both RSA-encrypted with the server’s public key:

• A 16-byte shared secret — this becomes the AES key
• The verify token, echoed back to prove the client decrypted it correctly

let shared_secret = rsa.private_decrypt(&encrypted_secret, Padding::PKCS1)?;
let decrypted_token = rsa.private_decrypt(&encrypted_token, Padding::PKCS1)?;

assert_eq!(decrypted_token, verify_token);

Step 3 — Session Authentication

Before enabling encryption, the server must verify the client is who they claim to be. This involves computing a SHA1 hash — called the “server hash” — derived from the server ID (an empty string in modern versions), the shared secret, and the public key:

let server_hash = compute_server_hash("", &shared_secret, &public_key_der);

The server hash has a peculiarity: it can be negative. Java’s BigInteger.toString(16) produces a two’s complement hex representation, which means negative values are prefixed with a minus sign. Rust’s standard library doesn’t do this natively — getting this wrong means authentication will always fail and it took a while to track down.

pub fn compute_server_hash(server_id: &str, shared_secret: &[u8], public_key: &[u8]) -> String {
    let mut hasher = Sha1::new();
    hasher.update(server_id.as_bytes());
    hasher.update(shared_secret);
    hasher.update(public_key);
    let hash = hasher.finalize();

    // Java BigInteger two's complement hex formatting
    let bigint = BigInt::from_signed_bytes_be(&hash);
    format!("{:x}", bigint)
}

The server then calls Mojang’s session server to verify the player:

GET https://sessionserver.mojang.com/session/minecraft/hasJoined
    ?username=<name>&serverId=<hash>

A 200 response with a profile JSON means the player is authenticated. Anything else and you disconnect them.

Step 4 — AES-CFB8

Once authentication passes, all subsequent communication is encrypted using AES in CFB8 mode with the shared secret as both the key and the IV:

use aes::Aes128;
use cfb8::Cfb8;
use cfb8::cipher::{AsyncStreamCipher, NewCipher};

type AesCfb8 = Cfb8<Aes128>;

let encryptor = AesCfb8::new_from_slices(&shared_secret, &shared_secret)?;
let decryptor = AesCfb8::new_from_slices(&shared_secret, &shared_secret)?;

Every byte sent and received after this point passes through the cipher. The stream is symmetric — both sides encrypt with the same key and IV, decrypting on receipt.

The Packet Macro System

Implementing packets manually is tedious and error-prone. Each packet is just a struct with a specific serialisation format — read fields in order, write fields in order. This is exactly the kind of boilerplate that proc-macros eliminate.

I built packet_macro and packet_codec as separate crates. The macro derives Encode and Decode traits for any struct annotated with #[derive(Packet)]:

#[derive(Packet)]
pub struct LoginSuccess {
    pub uuid: Uuid,
    pub username: String,
    pub properties: Vec<Property>,
}

The macro expands this to:

impl Encode for LoginSuccess {
    fn encode(&self, buf: &mut BytesMut) {
        self.uuid.encode(buf);
        self.username.encode(buf);
        self.properties.encode(buf);
    }
}

impl Decode for LoginSuccess {
    fn decode(buf: &mut Cursor<&[u8]>) -> Result<Self> {
        Ok(Self {
            uuid: Uuid::decode(buf)?,
            username: String::decode(buf)?,
            properties: Vec::<Property>::decode(buf)?,
        })
    }
}

Adding a new packet is now a single struct definition. The macro handles everything else. This was one of the more satisfying parts of the project — the first time a new packet compiled and worked correctly without writing any serialisation code manually.

Async Architecture

The server runs on Tokio — Rust’s async runtime. Each client connection spawns a task that owns a read half and a write half of the TCP stream:

let (reader, writer) = stream.split();

tokio::spawn(async move {
    handle_client(reader, writer, server_state).await;
});

Tokio’s task scheduler handles thousands of concurrent connections efficiently across a thread pool sized to the machine’s CPU count. There’s no thread-per-connection overhead — the async model means a connection waiting on a network read consumes virtually no resources.

Dependencies

The Cargo.toml tells the full story of what’s involved:

[dependencies]
tokio       = { version = "1", features = ["full"] }
serde       = { version = "1.0", features = ["derive"] }
bytes       = { version = "1", features = ["serde"] }
rsa         = "0.9.7"
rand        = "0.8.5"
sha1        = "0.10.6"
aes         = "0.8.4"
cfb8        = "0.8.1"
cipher      = "0.4.4"
num-bigint  = "0.4.6"
reqwest     = { version = "0.12.9", features = ["json"] }
packet_macro = { path = "../packet_macro" }
packet_codec = { path = "../packet_codec" }

Each dependency has a specific purpose. Nothing is included without a reason.

What I Learned

The Minecraft protocol is well-documented but unforgiving. The SHA1 two’s complement formatting, the CFB8 IV being the same as the key, the precise ordering of fields in every packet — any deviation produces a client disconnect with no useful error message. You learn to read packet captures.

More broadly: implementing a protocol from scratch teaches you things that working above an abstraction layer never does. After Nebula, reading Spigot’s NMS internals feels familiar rather than opaque. The abstraction makes more sense when you understand what it’s abstracting.

The packet macro system was the architectural highlight. Building a proc-macro that generates correct serialisation code for arbitrary structs — and then watching it just work across every packet type — is the kind of leverage that makes Rust genuinely exciting to work in.

What’s Next

The current build covers Handshaking, Status, and Login states in full. Play state packets follow the same patterns — the macro system makes adding them straightforward. The foundation is the hard part. The rest is implementation.

View Repo

The intention is to offer a unique and fun way for players to challenge themselves intellectually, fostering cognitive growth while enjoying the immersive world of Minecraft. The games are crafted with Java and Spigot, utilizing GUI interfaces similar to server gadgets, ensuring accessibility and a seamless integration into the Minecraft gaming experience.

Dual N-Back:

In Dual N-Back, players are required to remember the sequence of visual and auditory stimuli and identify when the current stimuli matches the one presented 'n' trials ago.

Study: The original study by Susanne M. Jaeggi and Martin Buschkuehl (2008) demonstrated that training with Dual N-Back can lead to improvements in fluid intelligence.

CWM (Complex Working Memory):

WM involves challenging working memory tasks that require the simultaneous processing and storage of complex information.

Study: Klingberg et al. (2005) conducted a study showing that computerized training of working memory, including complex working memory tasks, can lead to improvements in fluid intelligence.

Mental Math:

Mental math exercises involve performing calculations in your head without the use of external aids.

Study: While specific studies on mental math games may be limited, general cognitive training involving arithmetic tasks has been associated with improved mathematical and fluid intelligence skills (Dahlin et al., 2008).

Corsi Block Tapping:

Description: Corsi Block Tapping assesses visuospatial working memory by requiring participants to reproduce a sequence of block taps.

Study: Kessels, van den Berg, Ruis, and Brands (2008) found that Corsi Block Tapping performance was associated with individual differences in fluid intelligence.

Memory Span:

Memory span tasks involve recalling a sequence of items in the same order as presented.

Study: Engle et al. (1999) demonstrated that working memory capacity, including memory span, is related to fluid intelligence.

PASAT (Paced Auditory Serial Addition Test):

PASAT assesses information processing speed and working memory by requiring participants to add a series of numbers presented at a fixed rate.

Study: Stuss, Stethem, and Poirier (1987) found that performance on the PASAT is related to executive functions and working memory, which are components of fluid intelligence.

In this article, I’ll explore the concept of bitboards and delve into the intricacies of move generation for each chess piece. This also serves as an informative guide, and collection of ideas, incase I need to come back in the future for recollection.

Note: Although I try to explain the moves concisely, to understand some of the code, you will likely need basic knowledge of bitwise operations, and/or boolean algebra.

A “bit” About Bitboards

A bitboard is a compact data structure that represents the state of a chessboard using a series of 64-bit integers. Each bit in the integer corresponds to a square on the chessboard, and its state (0 or 1) represents the presence or absence of a piece on that square. Bitboards provide an efficient way to perform bitwise operations, enabling rapid computation of various chess-related tasks.

The foundations of bitboards lies in their efficiency, especially when it comes to bitwise operations. This efficiency arises from the binary nature of computation, allowing for rapid manipulation of chess-related tasks. Bitwise AND, OR, XOR, and shifting operations become powerful tools in the hands of developers when dealing with these data structures.

Calculating Move Generation

Each chess piece can be represented by a separate bitboard, simplifying move generation. The logical operations between these bitboards efficiently compute possible moves, legal positions, and attack vectors.

The following code snippets are provided for informational purposes and to illustrate the concepts of move generation in chess. It is important to note that these code snippets may need to be adapted and integrated into a broader chess engine implementation. Consider consulting official documentation and thoroughly testing any code in a suitable development environment.

The Pawn

Color Definition

• Assigns numeric values (0 for WHITE, 1 for BLACK) representing the colors of chess pieces.

Single Move Forward

• Calculates the target square for a single move forward based on the piece’s color. Checks if the target square is within the chessboard boundaries and unoccupied.

Double Move Forward (on the first pawn move)

• Considers the piece’s starting rank (second for white, seventh for black). If applicable, calculates the double move square and checks its validity.

Capture Diagonally

• Determines squares diagonally adjacent to the piece for potential captures. Checks if the capture squares are within the board, occupied by an opponent’s piece, and not blocked by friendly pieces.

Return value

• Returns a long integer (bitboard) with bits set for all valid pawn moves from the given square, considering single and double moves as well as captures.

    private static final int WHITE = 0;
    private static final int BLACK = 1;

    public static long generatePawnMoves(int square, int color, long occupied, long enemyPieces) {
        long moves = 0L;

        int targetSquare = square + ((color == WHITE) ? 8 : -8);
        if ((targetSquare >= 0 && targetSquare < 64) && ((occupied & (1L << targetSquare)) == 0)) {
            moves |= (1L << targetSquare);

            if (((color == WHITE) && (square / 8 == 1)) || ((color == BLACK) && (square / 8 == 6))) {
                int doubleMoveSquare = square + ((color == WHITE) ? 16 : -16);
                if ((doubleMoveSquare >= 0 && doubleMoveSquare < 64) &&
                        ((occupied & (1L << doubleMoveSquare)) == 0) &&
                        ((occupied & (1L << targetSquare)) == 0)) {
                    moves |= (1L << doubleMoveSquare);
                }
            }
        }
        int[] captureSquares = {(color == WHITE) ? square + 7 : square - 7, (color == WHITE) ? square + 9 : square - 9};
        for (int captureSquare : captureSquares) {
            if ((captureSquare >= 0 && captureSquare < 64) &&
                    ((occupied & (1L << captureSquare)) != 0) &&
                    ((1L << captureSquare) & enemyPieces) != 0) {
                moves |= (1L << captureSquare);
            }
        }
        return moves;
    }

The Knight (Majestic Horse)

Directional Movements

• Defines possible knight moves as horizontal and vertical components.

Generating Moves

• Iterates through directions to calculate potential target squares. Sets corresponding bits in the moves bitboard for valid and unoccupied target squares.

Return value

• Returns a long integer (a bitboard) with bits set for all valid knight moves from the given square.

 public static long generateKnightMoves(int square, long occupied) {
        long moves = 0L;
        int[] directions = {6, 10, 15, 17, -6, -10, -15, -17};

        for (int direction : directions) {
            int targetSquare = square + direction;
            if ((targetSquare >= 0 && targetSquare < 64) && ((occupied & (1L << targetSquare)) == 0)) {
                moves |= (1L << targetSquare);
            }
        }
        return moves;
    }

The Bishop

Diagonal Movement

• Represents bishop moves as diagonal paths on the chessboard.

Generating Moves:

• Iterates through diagonal directions to calculate potential target squares. Sets corresponding bits in the moves bitboard for valid and unoccupied target squares.

Return value

• Returns a long integer (bitboard) with bits set for all valid bishop moves from the given square.

public static long generateBishopMoves(int square, long occupied) {
    long moves = 0L;
    int[] directions = {7, 9, -7, -9};

    for (int direction : directions) {
        int targetSquare = square + direction;
        while (targetSquare >= 0 && targetSquare < 64 && ((occupied & (1L << targetSquare)) == 0)) {
            moves |= (1L << targetSquare);
            targetSquare += direction;
        }
    }
    return moves;
}

The Rook

Orthogonal Movement

• Represents rook moves as orthogonal paths on the chessboard.

Generating Moves

• Iterates through orthogonal directions to calculate potential target squares. Sets corresponding bits in the moves bitboard for valid and unoccupied target squares.

Return Value

• Returns a long integer (bitboard) with bits set for all valid rook moves from the given square.

public static long generateRookMoves(int square, long occupied) {
    long moves = 0L;
    int[] directions = {8, 1, -8, -1};

    for (int direction : directions) {
        int targetSquare = square + direction;
        while (targetSquare >= 0 && targetSquare < 64 && ((occupied & (1L << targetSquare)) == 0)) {
            moves |= (1L << targetSquare);
            targetSquare += direction;
        }
    }
    return moves;
}

The Queen

Combination of Bishop and Rook Moves

• Combines the movement patterns of bishops and rooks, allowing both diagonal and orthogonal paths.

Generating Moves

• Iterates through combined diagonal and orthogonal directions to calculate potential target squares. Sets corresponding bits in the moves bitboard for valid and unoccupied target squares.

Return Value

• Returns a long integer (bitboard) with bits set for all valid queen moves from the given square.

public static long generateQueenMoves(int square, long occupied) {
    long moves = 0L;
    int[] directions = {7, 9, -7, -9, 8, 1, -8, -1};

    for (int direction : directions) {
        int targetSquare = square + direction;
        while (targetSquare >= 0 && targetSquare < 64 && ((occupied & (1L << targetSquare)) == 0)) {
            moves |= (1L << targetSquare);
            targetSquare += direction;
        }
    }
    return moves;
}

The King

Adjacent Movements

• Represents king moves as adjacent squares in all eight directions.

Generating Moves

• Iterates through all directions to calculate potential target squares. Sets corresponding bits in the moves bitboard for valid and unoccupied target squares.

Return Value

• Returns a long integer (bitboard) with bits set for all valid king moves from the given square.

public static long generateKingMoves(int square, long occupied) {
    long moves = 0L;
    int[] directions = {7, 8, 9, -7, -8, -9, 1, -1};

    for (int direction : directions) {
        int targetSquare = square + direction;
        if (targetSquare >= 0 && targetSquare < 64 && ((occupied & (1L << targetSquare)) == 0)) {
            moves |= (1L << targetSquare);
        }
    }
    return moves;
}

To Conclude

If you got this far, congratulations! The idea behind bitboards is relatively simple, however implementations can certainly be nuanced.

I have quite a few creative ideas that can be implemented for different variants of Chess, so this post was made minimal and concise for viewer understanding.

Recommendations

• A video visually explaining bitboards by Holistic3D here

• The chessprogramming.org wiki articles here

If you’d like to play a chess game, contact me!

Features

1. Vertex Creation/Removal
2. Edge Creation/Removal
3. New graph state
4. Algorithms input, as well as built-in testing algorithms

Early Development Footage

You’ll be able to access the repository, and download once I release the application here.

lri is a project born out of a desire to deepen my understanding of the Rust programming language. As a passionate developer, I recognized the value of hands-on experience, and building an interpreter provided an excellent opportunity to explore Rust’s unique features and challenges.

1. What is an Interpreter?

An interpreter is a program that reads and executes code directly, without the need for a separate compilation step. It takes source code as input and interprets it on the fly, executing the instructions one at a time which can be useful for ease of development, portability, dynamic typing, and more.

Some popular languages which commonly use interpreters include:

• Python
• Javascript
• Ruby
• PHP

2. Lexical Analysis:

Lexical analysis is the process of breaking the input code into meaningful units called tokens. Tokens are the smallest units of a program, such as keywords, identifiers, literals, and operators. In the context of lri, lexical analysis involves scanning the input Rust code and identifying and categorizing these tokens.

struct Lexer { input: Vec<char>, position: usize, read_position: usize, ch: char }

impl Lexer {
    pub fn new(input: &str) -> Lexer { Lexer { input: input.chars().collect(), position: 0, read_position: 0, ch: '\0' } }
    fn next_token(&mut self) -> Token { self.skip_whitespace(); let token = match self.ch { '=' => Lexer::new_token(TokenKind::ASSIGN, self.ch), ';' => Lexer::new_token(TokenKind::SEMICOLON, self.ch), '('..='}' => Lexer::new_token(TokenKind::from(self.ch), self.ch), _ => Lexer::classify_token(self.ch), }; self.read_char(); token }
    fn classify_token(ch: char) -> Token { match ch { _ if Lexer::is_letter(ch) => Token { kind: lookup_ident(&self.read_identifier()), literal: String::new() }, _ if Lexer::is_digit(ch) => Token { kind: TokenKind::INT, literal: self.read_number() }, _ => Lexer::new_token(TokenKind::ILLEGAL, ch), } }
}

3. Parsing

Parsing is the process of taking the stream of tokens generated by lexical analysis and converting it into a structured representation, often represented as an Abstract Syntax Tree (AST). The AST reflects the hierarchical structure of the code and makes it easier to analyze and execute.

fn parse(tokens: Vec<Token>) -> ASTNode {
    // Implementation of parsing goes here
    // Build an Abstract Syntax Tree (AST) from the tokens
    // Return the root of the AST
}

Work in Progress (WIP)

Given that lri is in its early development stages, this was a showcase of how some of the systems function, in simplistic terms.

Remember, this is a simplified representation, and the actual implementation may involve more complexity, especially considering the features and nuances of the Rust programming language.

You can view the repository here

Multiple Objects are interactable

At the heart of this project lies a meticulously designed 3D mesh representation of my bedroom, complemented by a creative loading screen that sets the stage for an immersive experience. Engage with the interactive portfolio, where the computer monitor reveals insights about the creator and showcases a dynamic portfolio screen.

Beyond the Ordinary

• Chessboard Challenge: You are able to immerse yourself in a game of chess on a thoughtfully designed chessboard.
• Mirror Reflection: A mirror that reflects more than just a visual representation.
• First Person Controls: A first-person perspective that puts you in the center of this digital adventure.

Improving Performance

Here will be a glimpse of how I worked to improve performance, and reduce load times.

How did I know when the performance was declining?

Firstly, it’s important to understand that there can be a multitude of different reasons for ill-performance during development, especially game development, and performance issues are usually quite simple to track down.

I used a performance monitor to track the stress of the GPU/CPU of my scene - using this, I was able to easily discover issues I had made. Before I proceed, I’d like to note that the creation and manipulation of 3D objects are managed by the CPU, and the rendering and display of meshes occur on the GPU. Let’s proceed.

Here is a basic component, similar to how I loaded my GLTF textures:

export function Room(props: JSX.IntrinsicElements['group']) {
  const { nodes, materials } = useGLTF('/Portfolio_room.glb') as GLTFResult;
  const { isVisible } = useContext(VisibilityContext);

  const bedRef = useRef();
  const roomRef = useRef();

  return (
    <>
      <group {...props} dispose={null} ref={roomRef}>
        <group name="Bed" ref={bedRef}>
          <mesh
            name="Bed_Pillows"
            geometry={nodes.Box002_Baked.geometry}
            // material={materials.Objs2_Baked}
            position={[-6.907, 2.052, -0.094]}
            rotation={[-0.898, 0, 0]}
            material={materials.Objs2_Baked}
            userData=
          />
      </group>
        </group>
    </>
  );

This component was called inside another component like this:

export default function loading() {
  const [isRoomVisible, setRoomVisible] = useState(true);

  useEffect(() => {
    const animationFrameId = requestAnimationFrame(() => {
      setRoomVisible((prevVisible) => !prevVisible);
    });

    return () => cancelAnimationFrame(animationFrameId);
  });

  return <>{isRoomVisible && <Room />}</>;
}

The code above isn’t correct, but why? Well, because the room is being set visible on every frame, which will cause strenuous load on the GPU and CPU - Imagine every time you walked downstairs, you ended up on top of the stairs, after a while you’re going to become tired, and as such, the website eventually will become unusable. Let’s dive deeper.

Utilizing Big O Notation

What is the “Big O”?

Big O notation is a way to describe the efficiency of an algorithm or the performance of a piece of code. It provides a standardized method for expressing the upper bound of the time complexity or space complexity of an algorithm in relation to its input size.

In simpler terms, Big O notation helps us understand how the performance of an algorithm scales as the size of the input (e.g., the number of elements in a list) increases. It’s a way to analyze and compare algorithms, enabling us to choose the most efficient solution for a given problem.

Let’s say you use a loop to manipulate pixels in an 2D array of a large image like this:

for (let i = 0; i < images.length; i++) {
  for (let j = 0; j < images.length; j++) {
    // Simulate manipulation of pixels inside an image
  }
}

This loop is running in quadratic time complexity O(n^2). Can we achieve faster performance?

Since our pixels are stored inside a 2D array, if we know the image width and height, we can linearly loop through the image width * height, and get each pixel inside the array using some arithmetic like so:

const imageWidth = 42;
const imageHeight = 21;

for (let i = 0; i < imageWidth * imageHeight; i++) {
  const row = Math.floor(i / imageWidth);
  const col = i % imageWidth;

  // Simulate manipulation of pixels inside an image
  const pixelValue = pixels[row][col];
  // Do something with the pixel value
}

It’s important to be cognizant of little changes like these which improve the time complexity to linear O(n). This was a more simpler example of how I improved performance of various parts of code inside my codebase.

Updates

• I expect to release the site this year, and at the time Im writing this post I’m getting close to a beta build.
• The Chess board uses a design similar to bitboard engines, we love bytes!
• Recently implemented working Computer Monitors

Here’s a sneak peak of the loading scene (low fps gif):

The Design

I find it quite important to start any large project with some form of design documentation so that there’s a centralized, and highly specialized location of ideas, and sharing the documentation with others developers (if you work on a team).

If I have some form of control with design then I tend to go with mind maps for clarity. This is the approach I used within contract positions, and during freelance development.

Below will contain the features, followed by an example design documentation.

Linear Levelling Progression

• The required XP increases linearly with the player’s level.
• Example: 2500, 5000, 7500, etc.
• Customizable: Base increase of 3500*n.

Exponential Levelling Progression

• The required XP increases exponentially with the player’s level.
• Common in MMOS/RPGs like WoW.

Polynomial Levelling Progression

• The required XP increases according to a power of the player’s level.
• Similar to games like FFXIV, POE, Diablo 3, Skyrim, Oblivion.

Boosters

• Boosters are implemented to enhance XP gain for players.
• Customizable: Boost percentages, duration, etc.

Discord Integreation

• Discord integration for level updates by proxy.

Notifiers for Best Player Experience

• includes notifiers to enhance the overall player experience.

Psychology Utilization

• Utilizes researched psychological principles to optimize player engagement.

Customization

• The system allows for easy customization of XP progression via config.

Now the features are transparent, I spent time creating a design doc.

It’s important to encapsulate all the features, as well as any additional ideas you can think of, let yourself be creative. Here’s an image of the documentation:

The Map Anatomy

At first glance it may be difficult to understand the map, so I’ll break it down:

• The whole system of network levelling is a child of an abstract network statistic class for the server, since levelling should be tracked, this also means we’ll be able to easily manipulate other statistics, especially with boosters.

/**
 * This class represents a network statistic.
 */
public abstract class NetworkStatistic {

	protected static final List<String> availableStats = new ArrayList<>();

	protected int value;
	protected String name;
	protected String type;
	protected UUID player;
}

• Most of the features we discussed earlier are then a child of network levelling or listen in some way to network levelling.

public class Booster<T extends NetworkStatistic> {

	private final String boosterName;
	private final UUID playerUUID;
	private final T statistic;
}

Notice how I didn’t use a raw type of NetworkStatistic, this was peril not to do. Having a generic type of NetworkStatistic allow us to instantiate boosting for different types of network statistics, which also helps to be proactive for any future additions of network statistics, and this was the basis for how I started the project.

Player Psychology

It’s important to me that the systems I create, are as fun, intuitive, and enjoyable as possible for players. I think of players as customers, and so understanding your target audience is very important.

Here are the steps I took to create an engaging system:

• Horizontal progression over vertical (unlock new abilities, rather than making players more powerful; make them feel special)
• Visual progression system with available tracking will give small amounts of dopamine
• Rewards for levelling give an incentive to keep investment
• Purchasing boosters can offer great benefits to players of the server to achieve rewards faster (increasing ROI)

Discord Integration

This was simply achieved through a HTTPS connection to the url of a discord channel. All the functionality to post was customizable for admins (thumbnails, footers, content, titles, rgb support, and more).

URL url = new URL(this.url);
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();

Conclusion

• Be ready to make vast changes; concepts aren’t final.
• Over the years creation has become more trivial, but creating something that’s meaningful requires a lot more dedication.
• Research, and then research some more

You can find a link to my repository, containing fully documented code of a basic implementation, similar to how I’ve incorporated network levelling for servers in the past View Repo

I had an idea about creating a ‘raid’ minigame for Minecraft, similar to MMOs like WOW, FFXIV, Destiny 2, and then I thought it’d be even more fun to create raid abilities, as I’d be able to flesh out the abilities much faster, and a lot of people enjoy seeing cool animations.

Here I’m going to discuss one of the abilities I called “Torture”, and show early development footage.

Torture (raid ability)

Torture is a high mana ability due to it’s power, use carefully.

This was the initial adage I had in mind when creating, but first some Math.

Why Quadratic Equations

Quadratic equations are mathematical expressions of the form ax^2+bx+c=0, representing parabolic curves. In Minecraft, they can be useful for visual effects by simulating realistic projectile motion, creating aesthetic designs, and adding dynamic elements to abilities or spells. The parabolic nature of quadratic equations suits the trajectory of particles, enhancing the visual experience in the game.

Knowing this, I incorporated a few equations to calculate certain parameters related to trajectory, positions, and timing of particle effects.

Particle Effects

This can be achieved using NMS (Net Minecraft Server), which is used to access the server code of Minecraft, allowing the sending of packets with bundled data for more control. Here’s what a basic packet of data relating to particle effects might look like:

PacketPlayOutWorldParticles packet = new PacketPlayOutWorldParticles(particleType, true,
                particleX, particleY, particleZ, offsetX, offsetY, offsetZ, speed, count);

((CraftPlayer) player).getHandle().playerConnection.sendPacket(packet);

The Design

I initially drew a sketch of the ability, it was going to be used on an entity. When used the blocks around the entity within a radius rise, and then the blocks that rise are chosen pseudo-randomly to fly and cause destruction where the ability was used.

There also contains a circle for the ability location, and a square inside the circle for where most the damage is taken.

This was my original design, and there were iterations which contained a large square which was a region of containment, inside the region there would be totems that rise from the ground to inhibit damage from an explicit range using ray-tracing, this became the design of another ability.

Early Development Footage