
## 1. The Challenge: Godot's Scene Transition Desyncs

If you've spent any time working with Godot 4's high-level multiplayer API, you know that getting basic movement synced across a network is relatively painless. But the moment you try to hot-swap scenes—like moving players from a staging lobby into the actual game map—things get messy.

Out of the box, Godot's `MultiplayerSpawner` and `MultiplayerSynchronizer` nodes are incredibly powerful, but they have a fatal flaw when dealing with scene transitions: they expect everyone to be on the same page at the exact same time.

If the server loads the new scene instantly and starts broadcasting spawn instructions, any client still stuck on a loading screen will completely miss those instructions. Worse, they might throw hard errors and crash because the target spawn paths don't exist in their local scene tree yet.

To solve this boilerplate nightmare, I built a server-authoritative, [open-source multiplayer lobby template](https://github.com/RGonzalezTech/Friendslop-Template). The goal was simple: provide a 2D template that developers can fork, wipe the placeholder world, and immediately start building on top of a reliable networking foundation.

## 2. Architectural Approach: The Three Pillars

To keep responsibilities strictly separated, the system relies on three core autoloads (singletons):

### 1. PeerManager (The Network Gatekeeper)

The `PeerManager` handles the actual connection logic. It exposes a simple API for hosting or joining a game. Under the hood, it delegates the actual networking to an abstract `NetworkProvider` class. Currently, it implements standard UDP/ENet connections, but this abstraction makes it trivial to swap in Steam or WebSockets later without touching the core game logic. You simply pass a configuration object to the provider on initialization, and it handles the rest.

### 2. LobbyManager (The Source of Truth)

This node acts as the server-authoritative state machine. It holds the lobby configuration, tracks max players, and manages `LobbyPlayer` nodes containing metadata for each connected user (e.g., their name and status: `scene_loading`, `synced`, or `in_game`).

Crucially, it also holds an `active_map` string property. The `LobbyManager` broadcasts all of this state to clients using a `MultiplayerSynchronizer`. Clients cannot change this state directly; they must send RPC requests to the server.

### 3. SceneManager (The Transition Handler)

Instead of relying on a hard freeze during `get_tree().change_scene_to_file()`, the `SceneManager` handles transitions gracefully. It fades in a loading overlay, background-loads the heavy scene resources on a separate thread, swaps the scene tree once ready, and manages the fade-out.

## 3. The Secret Sauce: The Loading Handshake

The real fix to the desync issue happens between the `SceneManager` and the server. We don't just dump players into the game the millisecond their local scene finishes loading. We use a strict handshake protocol.

Here is the flow of how the server and clients negotiate a map change without crashing:

<pre class="mermaid">
sequenceDiagram
    participant Server (LobbyManager)
    participant Client (LobbyManager)
    participant Client (SceneManager)

    Note over Server (LobbyManager), Client (SceneManager): The server decides to start the game
    Server (LobbyManager)->>Server (LobbyManager): Update `active_map` string
    Server (LobbyManager)->>Client (LobbyManager): Broadcast new `active_map` via Synchronizer
    
    Client (LobbyManager)->>Client (SceneManager): Detect map change, request load
    Client (SceneManager)->>Client (SceneManager): Fade UI, background load resource
    Client (SceneManager)->>Client (SceneManager): Swap Scene Tree
    
    Note over Client (SceneManager): Map is fully loaded locally
    Client (SceneManager)->>Client (LobbyManager): Emit `done_loading` signal
    Client (LobbyManager)->>Server (LobbyManager): RPC: "Change my status to synced!"
    
    Server (LobbyManager)->>Server (LobbyManager): Update client status to `synced`
    Note over Server (LobbyManager): Server now knows it is safe to spawn the player
    Server (LobbyManager)->>Client (SceneManager): MultiplayerSpawner instantiates player character
</pre>

## 4. Conclusion

By forcing the server to wait for individual clients to report their local status via RPC, we completely eliminate the race conditions that break out-of-the-box multiplayer spawners. Fast loaders get in quickly, slow loaders don't crash, and the server maintains total authority over the game state.

Building multiplayer games as a solo dev is tough enough without wrestling with synchronization crashes. This template abstracts away the painful boilerplate, leaving you free to focus on what actually matters: making a fun game.

Check out the repo on Github here: [Friendslop Template](https://github.com/RGonzalezTech/Friendslop-Template)

<blockquote class="bluesky-embed" data-bluesky-uri="at://did:plc:bovkdy4olcmr6szh5qgevyab/app.bsky.feed.post/3mfb2lcqsv22u" data-bluesky-cid="bafyreid5v7q64b42vw34i7aoa6hlleop72uqu4c2vq43h2rqipnawovx6y" data-bluesky-embed-color-mode="system"><p lang="en">Hey yall, I built an #opensource (MIT) #godot 4 starter kit for multiplayer. I designed it as a genre-agnostic framework that I can fork for each co-op idea I want to explore.

Wanted to add more, but I should probably work on my ideas now 😅 #FOSS

github.com/RGonzalezTec...<br><br><a href="https://bsky.app/profile/did:plc:bovkdy4olcmr6szh5qgevyab/post/3mfb2lcqsv22u?ref_src=embed">[image or embed]</a></p>&mdash; Raul Gonzalez | Computer Nerd (<a href="https://bsky.app/profile/did:plc:bovkdy4olcmr6szh5qgevyab?ref_src=embed">@rgonzaleztech.bsky.social</a>) <a href="https://bsky.app/profile/did:plc:bovkdy4olcmr6szh5qgevyab/post/3mfb2lcqsv22u?ref_src=embed">February 19, 2026 at 6:25 PM</a></blockquote><script async src="https://embed.bsky.app/static/embed.js" charset="utf-8"></script>


## Challenge: A Critical Tool Falling Behind

In any software ecosystem, automated testing is the bedrock of quality. For the Godot game engine, the community often uses the [Godot Unit Test (GUT)](https://github.com/bitwes/Gut) library. To integrate this unit test library into modern development workflows, the [`godot-tester` action](https://github.com/croconut/godot-tester) was created, allowing developers to automatically run their unit tests as part of a CI/CD pipeline.

In late 2022, I encountered an issue when leveraging the `godot-tester` action on a pet project of mine. I noticed that [the github issue covering the problem](https://github.com/croconut/godot-tester/issues/22) had been open for 5 months. To summarize, the GUT testing library had updated its test result format to JUnit XML, but the `godot-tester` action hadn't been updated to parse it. At this time, I learned that the github action was implemented as a single bash script. While I submitted a patch to the bash code to fix the immediate issue, I saw the deeper challenge: the project's complexity was outgrowing its bash foundation, making it difficult to maintain and adapt.

This became critical when [a request for Godot 4 support](https://github.com/croconut/godot-tester/issues/26) was opened in November 2022. For months, the issue saw no activity. The technical hurdles were significant enough that modifying the monolithic script was a daunting task for potential contributors.

## The Evolution: A Three-Stage Modernization

Seeing the community's need, I decided to take ownership of the modernization effort. Instead of a single "big bang" rewrite, I approached it as a pragmatic, three-stage evolution.

### Stage 1: Improving the Bash Foundations (May 2023)

My first step wasn't to start adding new features, but to make the existing codebase manageable. I first tried to empower the community by detailing the required changes in the open issue, providing a clear path forward. After a month passed with no activity, I took ownership of the changes. I refactored the monolithic bash script, extracting logic into named functions and creating a `lib/` directory. This made the code more readable and, crucially, lowered the barrier for any future contributions.

### Stage 2: Delivering Godot 4 Support with Backward Compatibility (June 2023)

With the refactored script in place, I implemented support for Godot 4. This was done carefully, creating switch branches based on the user's specified Godot version (3.x or 4.x) which adjusted the script's behavior accordingly. This ensured that we could introduce a major new feature without breaking the workflow for the existing user base. This version was merged, successfully resolving a months-old community request.

### Stage 3: The Strategic Rewrite for Long-Term Health (July 2023)

Feeling like I was on a hotstreak after merging the Godot 4 support, I decided to address the project's remaining technical debt. While the bash script now worked, it was still a technical dead-end. It was difficult to test, prone to platform-specific issues, and not an ideal foundation for future features. A week after the Godot 4 support was merged, I proposed and executed a complete rewrite of the action in Node.js.

The new architecture was designed for maintainability, reliability, and extensibility:
*   **Node.js Core:** A more robust, platform-agnostic language for handling logic like downloading files, parsing XML, and interacting with the GitHub Actions environment.
*   **Docker Container:** The action now runs inside a Docker container, ensuring a consistent and predictable execution environment for every user.
*   **Unit Tests:** The new Node.js codebase is covered by unit tests, allowing for confident refactoring and feature development without fear of regressions.
*   **Modularity:** The code was split into multiple files, each with a single, isolated purpose (e.g., parsing inputs, downloading Godot, running tests, evaluating results).

<pre class="mermaid">
graph LR
    A((Start))--> B[Read Params/Args];
    B --> DownloadGodot;
    DownloadGodot --> RunGodotImport;
    RunGodotImport --> ExecuteGUTTests;
    ExecuteGUTTests --> AnalyzeTestResults;

    subgraph DownloadGodot[Download Godot]
        C1[Generate Download URL] --> C2[Perform Download];
        C2 --> C3[Decompress ZIP];
        C3 --> C4[Find Executable];
    end

    subgraph RunGodotImport[Run Godot Asset Import]
        D1[Add Rebuilder Scene] --> D2[Run Godot in Headless Editor Mode];
        D2 --> D3[Remove Rebuilder Scene];
    end

    subgraph ExecuteGUTTests[Execute GUT Tests]
        E1[Construct GUT CLI Args] --> E2[Run Godot with GUT Script];
    end

    subgraph AnalyzeTestResults[Analyze Test Results]
        F1[Read XML File] --> F2[Parse XML Data];
        F2 --> F3[Calculate Pass Rate];
        F3 --> F4[Compare with Minimum Pass/Max Fails];
    end

    AnalyzeTestResults --> CheckPassRate{Failure<br/>threshold<br/>met?}
    CheckPassRate -->|Too Many Failures| Fail;
    CheckPassRate -->|All passed| Success;
</pre>

## The Results: A Revitalized Community Tool

The migration from a legacy bash script to a modern Node.js application transformed the `godot-tester` action from a maintenance challenge into a stable and extensible platform.

*   **Improved Reliability:** The Docker container and unit tests ensure the action behaves consistently and correctly across different environments.
*   **Enhanced Maintainability:** The modular, well-tested codebase is significantly easier for new contributors to understand, modify, and extend.
*   **Future-Ready:** The new architecture makes it easier to add features and support future versions of Godot.

This modernization effort shows how an iterative approach can breathe new life into a valuable open-source project. By breaking down the problem—first improving the existing script, then adding features, and finally rewriting for long-term health—the tool was updated to meet the community's current and future needs. The project is now in a much better position for continued community contribution and evolution.



## 1. The Challenge: Creating a Persistent and Engaging Multiplayer Experience

For many multiplayer games, community engagement is key to a vibrant, long-lasting player base. While hosting a dedicated server for a game like *Project Zomboid* provides a persistent world, it lacks integration with the community's primary communication platform—in our case, Discord.

The challenge was twofold:
1.  **Deploy and manage a stable, 24/7 dedicated game server** with custom configurations and mods.
2.  **Bridge the gap between the game server and our Discord community** by developing custom tools to provide real-time event notifications, player statistics, and server status information.

## 2. Solution Part I: Dedicated Server Deployment and Management

The foundation of this project was a dedicated *Project Zomboid* server. I used **LinuxGSM** to streamline the installation and management process on a Linux VM. This provided a robust command-line interface for handling updates, backups, and server startups/shutdowns.

```bash
# Example LinuxGSM commands for server administration
./pzserver start   # Start the server process
./pzserver update  # Check for and apply SteamCMD updates
./pzserver backup  # Create a compressed backup of the server state
```

Server configuration and mod management were handled by modifying the `.ini` and `.lua` files, allowing for a highly customized gameplay experience tailored to our group.

## 3. Solution Part II: Custom Discord Bot Suite

To enhance community engagement, I developed a suite of TypeScript-based services that parse game logs and interact with the Discord API.

### A. Real-Time Death Notifications

**Problem:** Player deaths are significant events in *Project Zomboid*. We wanted a way to share these moments with the community in real-time.

**Solution:** I developed a service that actively monitors the server's `PerkLog` file. When a new line is added, the script uses a regular expression to check if it's a death event.

```typescript
// Regex to capture player name and hours survived from a log line
const deadLinePattern = /\[[\d\- :\.]+\] \[\d+\]\[(.+)\]\[\d+,\d+,\d+\]\[Died\]\[Hours Survived: (\d+)\]\./;
```

If a match is found, the script performs two actions:
1.  **Sends a Discord Webhook:** A message is immediately sent to a designated channel, announcing the death and how long the character survived.
2.  **Logs to SQLite:** The event data (player name, hours survived, timestamp) is stored in an SQLite database for future analysis.

<pre class="mermaid">
sequenceDiagram
    participant Game Server
    participant Log File
    participant TypeScript Service
    participant SQLite DB
    participant Discord Webhook

    Game Server->>Log File: Appends player death event
    TypeScript Service->>Log File: Watches for file changes and reads new line
    TypeScript Service->>TypeScript Service: Matches line with Regex
    TypeScript Service->>SQLite DB: Stores death event data
    TypeScript Service->>Discord Webhook: Sends formatted notification
</pre>

### B. Weekly Leaderboard

**Problem:** We wanted a fun, competitive way to track player stats and celebrate (or commiserate) our collective efforts.

**Solution:** A second TypeScript script was created to query the SQLite database. It calculates the total number of deaths and hours survived for each player, ranking them in a "Zombie-Darwin Awards" leaderboard. This script is scheduled to run weekly as a `cron` job, automatically posting the updated leaderboard to Discord.

### C. `/online` Player Status Command

**Problem:** Players wanted an easy way to check who was currently online without having to launch the game.

**Solution:** This required a more integrated approach.
1.  **Custom Lua Mod:** I wrote a simple in-game mod in Lua that hooks into the server's tick cycle. Every 900 ticks (~15 seconds), it writes the current list of online players and their stats (profession, kills, hours alive) to a dedicated log file.
2.  **Watcher Service:** A TypeScript service monitors this new log file. When the file is updated, it parses the content and saves the current player list to a structured `players.json` file.
3.  **Discord Bot:** A separate Discord bot application was created. It registers a slash command (`/online`). When a user executes the command, the bot reads the `players.json` file and presents the data in a clean, embedded format in the Discord channel.

This three-part system effectively provides a near real-time view of the server's status directly within Discord.

## 4. Results and Impact

This project successfully transformed a standard game server into a deeply integrated community hub.
*   **Increased Engagement:** The real-time notifications and leaderboards sparked conversations and brought a new level of shared experience to the game.
*   **Valuable Automation:** The system operates autonomously, requiring no manual intervention to provide continuous, valuable insights to the community.
*   **Demonstrated Technical Skills:** The project showcases a range of skills, including:
    *   **Server Administration:** Deploying and managing a Linux-based game server.
    *   **Backend Development:** Writing services in TypeScript to parse data, interact with a database, and call external APIs.
    *   **Game Modding:** Creating a custom Lua mod to extract in-game data.
    *   **DevOps:** Using tools like `cron` for scheduling and SQLite for data persistence.

This case study demonstrates the ability to identify a need within a community and build a full-stack, automated solution to meet that need, creating a more engaging and connected user experience.


## 1. The Challenge: Modernizing a Monolithic Application

My personal website and blog were originally built as a standard Ruby on Rails application, hosted on a virtual machine with DigitalOcean. While functional, this monolithic architecture presented several key challenges:

*   **High Maintenance Overhead:** Required manual server maintenance, security patches, and scaling management.
*   **Cost Inefficiency:** A fixed monthly cost for the VM, regardless of traffic levels.
*   **Slow Deployment Cycle:** The deployment process was manual and time-consuming, hindering rapid iteration.
*   **Performance Limitations:** As a dynamic application, it couldn't fully leverage the speed benefits of modern static site generation.

The goal was to re-platform the website to a modern, serverless architecture that would be more performant, scalable, cost-effective, and easier to maintain.

## 2. The Solution: A Serverless Frontend with Automated CI/CD

I architected a new solution centered on Next.js for the frontend, AWS for infrastructure, and GitHub Actions for automation. This decoupled the frontend from a traditional backend server, embracing a static-first approach.

### Technical Architecture

The core components of the new architecture are:

*   **Next.js Framework:** Chosen for its powerful Static Site Generation (SSG) capabilities, which pre-renders the entire website into highly optimized HTML, CSS, and JavaScript files at build time. This dramatically improves performance and SEO.
*   **AWS S3:** Used as the primary storage for all static assets. S3 provides durable, inexpensive, and highly available object storage, eliminating the need for a traditional web server.
*   **AWS CloudFront:** A global Content Delivery Network (CDN) that caches the site's assets at edge locations around the world. This ensures low-latency delivery to users everywhere and provides a security layer with a custom SSL certificate.
*   **GitHub Actions for CI/CD:** An automated workflow was established to handle the entire build and deployment process. On every new release pushed to the GitHub repository, a GitHub Actions runner automatically:
    1.  Builds the Next.js application.
    2.  Generates the static HTML files for all blog posts.
    3.  Uploads the entire build output to the S3 bucket.
    4.  Invalidates the CloudFront cache to ensure the latest version is served.

<pre class="mermaid">
graph LR
    subgraph "Development Workflow"
        A[GitHub Repository] -->|Publish Release| B[GitHub Actions]
    end
    subgraph "Build & Deploy Pipeline"
        B -->|1. npm run build| C[Static Site Generation]
        C -->|2. Upload to S3| D[(AWS S3 Bucket)]
        D -->|3. Invalidate Cache| E[AWS CloudFront]
    end
    subgraph "User Access"
        F[User Browser] -->|www.rgonzalez.tech| E
    end
</pre>

### Content Management Transformation

The content workflow was also modernized. Instead of a database-backed CMS, all blog posts are now written in Markdown. This developer-centric approach, known as "Git as a CMS," has several advantages:
*   **Simplified Workflow:** I can write and edit content in any text editor and use version control (Git) to manage changes.
*   **No Database Needed:** Eliminates the cost and complexity of managing a database.
*   **Improved Performance:** Content is compiled directly into static HTML during the build process.

## 3. The Migration Process

Migrating from a Rails application with a SQLite database required a systematic approach.

*   **Content Export:** I leveraged a Python script within a Jupyter notebook (run via ChatGPT's data analysis feature) to query the `.sqlite` database. This script extracted all blog posts and their metadata into a structured format.
*   **Content Transformation:** The extracted data was then programmatically converted into individual Markdown files, complete with the necessary frontmatter (title, date, tags, etc.).
*   **Asset Migration:** A custom Ruby script was written to iterate through the Rails Active Storage attachments, download all image assets, and organize them into a new folder structure compatible with the Next.js project.

```ruby
# Snippet from the Rails asset migration script
ActiveStorage::Attachment.all.each do |attachment|
  blob = attachment.blob
  filename = attachment.filename.to_s
  new_path = "#{Rails.root}/tmp/migrated_assets/#{filename}"

  # Write the file to a temporary location for upload
  File.open(new_path, "wb") do |file|
    file.write(blob.download)
  end
end
```

## 4. The Results: A Measurable Improvement

The migration to a serverless architecture yielded significant, quantifiable benefits:

*   **Hosting Costs Reduced by >95%:** Moved from a fixed monthly VM cost to paying only for pennies-per-month S3 storage and CDN bandwidth, resulting in near-zero operational expense.
*   **Dramatically Improved Performance:** Achieved a Google PageSpeed Insights score of 95+ for performance, thanks to SSG and CDN caching.
*   **Zero-Maintenance Infrastructure:** The serverless model completely eliminated the need for server management, patching, or manual scaling.
*   **Accelerated Development Cycle:** The automated CI/CD pipeline reduced deployment time from a manual 15-minute process to a fully automated 2-minute workflow, enabling faster iteration and content updates.

This project successfully transformed a legacy monolithic website into a modern, high-performance, and cost-effective digital asset, showcasing the tangible business advantages of adopting a serverless-first mindset.


## 1. The Challenge: Designing a Scalable Interaction System

For a co-op game currently in development, I needed to architect an object interaction system that was both flexible and scalable. The system had to meet several key requirements from the outset:

*   **Versatility:** Support a wide range of interactable objects, from simple doors and levers to complex machinery.
*   **Multiple Interaction Types:** Handle both instantaneous "tap" interactions (like a button press) and sustained "hold" interactions (like repairing an engine).
*   **Context-Sensitivity:** Allow objects to be interactable only by specific players, roles, or those holding certain items.
*   **Co-op Ready:** Gracefully handle scenarios where multiple players might attempt to interact with the same object simultaneously.
*   **Extensibility:** Be easy for designers to implement on new objects without needing to rewrite core logic.

This document details the architectural design for this system in the Godot engine.

![](/images/blogs/Progress.gif)
*Early prototype demonstrating the need for a robust interaction system.*

## 2. Architectural Approach: A Decoupled, Event-Driven System

The core of the design is to keep the player and the interactable objects as decoupled as possible. The player should not need to know the specific details of any object it interacts with. Likewise, an object should not need a direct reference to the player. This is achieved using Godot's built-in **signals** and a standardized interface enforced via **duck-typing**.

### The Player's Role

The player character is responsible for three things:
1.  **Detection:** Identifying potential interactable objects within its vicinity (e.g., using an `Area3D` node).
2.  **Selection:** Determining which object is the current target and notifying it that it is "selected."
3.  **Input Broadcasting:** Emitting signals when the player presses or releases the interact button.

### The Interactable Object's Role

Any object that can be interacted with must conform to a specific interface by implementing a set of standard methods. In GDScript, we can check for this using `has_method()`. This approach avoids rigid class inheritance and allows any node to become interactable.

The required methods are:
*   `can_be_selected_by(player_node)`: Returns `true` or `false`. This is the gatekeeper method. It allows an object to define its own interaction prerequisites. For example, a heavy door might check if `player_node.role == "Warrior"`.
*   `on_selected(player_node)`: Called by the player when this object becomes the active target. The object is responsible for its own highlighting or UI feedback.
*   `on_deselected(player_node)`: Called when the player looks away or moves out of range.
*   `on_interact_start(player_node)`: Triggered when the player presses the interact button.
*   `on_interact_end(player_node)`: Triggered when the player releases the interact button.

## 3. The Interaction Flow

The entire process, from detection to interaction, follows a clear, event-driven sequence.

<pre class="mermaid">
sequenceDiagram
    participant Player
    participant Interactable Object

    Player->>Interactable Object: Detects object in range
    Player->>Interactable Object: call can_be_selected_by(self)
    Interactable Object-->>Player: return true

    Player->>Player: Set object as current selection
    Player->>Interactable Object: call on_selected(self)
    Interactable Object->>Interactable Object: Enable highlight/UI

    Note over Player: Player presses 'Interact'
    Player->>Interactable Object: call on_interact_start(self)
    Interactable Object->>Interactable Object: Begin interaction logic (e.g., open door)

    Note over Player: Player releases 'Interact'
    Player->>Interactable Object: call on_interact_end(self)
    Interactable Object->>Interactable Object: Finalize interaction logic

    Note over Player: Player moves out of range
    Player->>Interactable Object: call on_deselected(self)
    Interactable Object->>Interactable Object: Disable highlight/UI
</pre>

### Handling Multi-Player Scenarios

To manage simultaneous interactions in a co-op environment, each interactable object maintains a list of `players_currently_selecting`.

*   When `on_selected` is called, the player is added to the list. The highlight is enabled only if the list is not empty.
*   When `on_deselected` is called, the player is removed. The highlight is disabled only when the list becomes empty.

This ensures that the object remains highlighted as long as at least one player is targeting it, preventing flickering UI and race conditions.

## 4. Conclusion

This architectural design provides a robust and designer-friendly foundation for all object interactions in the game. By leveraging Godot's core features like signals and embracing a decoupled, interface-driven approach, the system is:

*   **Maintainable:** Logic is cleanly separated between the player and the objects.
*   **Scalable:** New and unique interactable objects can be created rapidly without modifying any existing player code.
*   **Co-op Ready:** The system is inherently designed to handle multiple players from the start.

This approach demonstrates how thoughtful architecture can solve complex gameplay requirements in a clean and efficient manner, paving the way for smoother development as the project grows.



## Introduction: The Vision

For years, I've been passionate about game development. In mid-2021, I embarked on a project to bring a long-held concept to life: a fast-paced, 3D action game inspired by the fluid, powerful movement seen in anime. The core design pillars were **Speed** and a **One-Versus-Many** combat dynamic. The goal was to create an experience where player skill, expressed through graceful movement and tactical combat, could overcome overwhelming odds.

This document serves as a postmortem of that prototype, detailing its development, the challenges faced, and the critical lessons learned about scope, solo development, and project management.

## Phase 1: Prototyping Core Mechanics (Builds 1-8)

The initial focus was on nailing the "feel" of the game. Working in Unity with C#, I prioritized the player controller and camera systems.

**Key Features Developed:**
*   **Movement System:** The foundation was a physics-based controller that emphasized momentum. Core abilities included a double jump and a critical mid-air dash, which became central to the game's flow.
*   **Enemy AI:** To complement the player's speed, the initial enemy AI was designed to penalize inaction. Melee enemies would chase, charge up an attack, and pounce, forcing the player to stay mobile.
*   **Combat System:** I implemented a basic combat loop with a sword for melee attacks and two returning boomerangs for ranged engagement.
*   **Wave Management:** A flexible wave manager script was created to control the spawning of enemies, allowing for designed combat encounters across a test arena.

![](/images/blogs/0.8.3.gif)
*Early prototype showcasing movement, combat, and the wave system.*

By the eighth build, the project had all the necessary systems for a complete game loop: a main menu, health/lose conditions, and a win condition (clearing all enemy waves). The core mechanics felt promising, but the path forward revealed significant challenges.

## Phase 2: The Challenge of Scope

As the prototype evolved, so did the list of requirements for a minimum viable product:

*   **Enemy Variety:** The game needed more than just one melee enemy type. I refactored the AI code into a component-based system, allowing for easier creation of new archetypes like ranged shooters. This modular approach, separating navigation, health, and combat behaviors, was a success.
*   **Level Design:** An empty arena was insufficient. A well-designed level that complemented the player's verticality and the enemy spawning system was critical.
*   **Art and Aesthetics:** The project used placeholder assets. A full release required a cohesive art style, 3D models, animations, particle effects, and a polished UI.
*   **Procedural Generation:** The long-term vision included procedurally generated waves to enhance replayability.

It became clear that the project's scope was far too ambitious for a solo developer working part-time. Each requirement represented a massive undertaking.

![](/images/blogs/WaveUI.gif)
*Later UI and system refinements, including Test-Driven Development practices.*

## Phase 3: Pivoting and Lessons Learned

The realization of the project's true scale led to a difficult but necessary decision: to pause development. This pivot was not a failure, but a strategic choice based on several key learnings.

### Lesson 1: The Perils of Unchecked Scope
My passion for the project led me to continuously add features, a classic case of "scope creep." While features like leaderboards and complex enemy AI were exciting, they weren't essential for validating the core concept.
**Takeaway:** A solo developer must be ruthless in prioritizing the absolute minimum required to create a fun experience.

### Lesson 2: The Value of Smaller, Shippable Projects
In an attempt to force a smaller scope, I challenged myself to build a complete multiplayer maze-racing app in just 12 days. I completed the core single-player mechanic quickly but then fell into the same trap, designing complex multiplayer features like rankings, skins, and stores. This experiment reinforced the primary lesson: the discipline to ship a small, polished product is a skill in itself.
**Takeaway:** The experience gained from completing and shipping a small project far outweighs that from an ambitious, unfinished prototype.

### Lesson 3: Differentiating a Hobby from a Product
My initial designs were influenced by monetization and user retention strategies. I realized this was distracting me from the core goal: making a game that was simply fun to play.
**Takeaway:** For personal projects, focusing on the intrinsic enjoyment of the creative process leads to better outcomes than prematurely optimizing for commercial success.

## Conclusion

Pausing "Project: Anime Motion" was the right decision. The prototype successfully validated the core mechanics and provided an invaluable, hands-on education in the realities of solo game development. The primary lesson was in understanding the critical importance of managing scope.

The experience has shifted my focus towards creating smaller, more polished games that I can complete and release. The skills honed in C#, Unity, AI programming, and system design during this project are directly applicable to future endeavors, but they will now be applied to projects with a much clearer and more realistic scope.


## 1. The Challenge: Persistent VPN for Domain-Joined Machines

In a corporate environment that leverages Microsoft Active Directory (AD), it is critical for domain-joined computers to maintain a persistent connection to a domain controller. This ensures that group policies are applied, authentication requests are processed, and security postures are maintained.

This requirement becomes a challenge when users work remotely. A standard user-initiated VPN connection is insufficient, as the VPN tunnel must be established *before* the user logs in to Windows. Without this pre-login connection, the machine cannot communicate with the domain controller, leading to authentication issues and policy failures.

## 2. The Solution: OpenVPN Connect as a Windows Service

The solution is to configure the OpenVPN client to run as a system service that starts automatically on boot, independent of any user session. The **OpenVPN Connect** client for Windows includes a command-line utility specifically for this purpose: `ovpnconnector.exe`.

This utility allows a system administrator to install and manage a system-wide VPN connection that initializes as part of the Windows startup sequence.

## 3. Implementation Steps

The process is straightforward and can be easily scripted for automated deployment.

### Step 1: Prepare the OpenVPN Profile

First, prepare the client `.ovpn` configuration file. This file contains all the necessary directives, certificates, and keys for the connection. For the service to recognize it, the file **must be named `ovpnconnector.ovpn`**.

### Step 2: Stage the Profile

Place the `ovpnconnector.ovpn` file in the installation directory of OpenVPN Connect. By default, this is typically:
`C:\Program Files\OpenVPN Connect\`

### Step 3: Install and Start the Service

Using an **elevated Command Prompt or PowerShell**, navigate to the OpenVPN Connect installation directory and execute the following commands:

```bash
# Navigate to the installation directory
cd "C:\Program Files\OpenVPN Connect"

# Install the service. This registers the ovpnconnector.ovpn profile.
.\ovpnconnector.exe install

# Start the service immediately.
.\ovpnconnector.exe start
```

Once installed, the "OpenVPN Connect Service" will be visible in the Windows Services console (`services.msc`) and will be configured to start automatically with the system.

## 4. Conclusion

By using the `ovpnconnector.exe` utility, system administrators can ensure that remote, domain-joined Windows machines maintain a persistent and secure connection to the corporate network. This pre-login VPN tunnel is essential for the proper functioning of Active Directory services in a remote work environment.

This method provides a reliable solution for policy enforcement and authentication, demonstrating a key technique for managing Windows clients in a distributed network architecture.



## 1. The Challenge: Beyond a Single Point of Failure

In any technical environment, from a personal home lab to a large enterprise, data is the most valuable asset. A simple backup is a good first step, but a truly resilient data strategy must account for multiple failure scenarios, including hardware malfunction, accidental deletion, and physical disasters like fire or theft.

Relying on a single backup location, even one with internal redundancy like a RAID array, creates a single point of failure. If the primary device is compromised, all data, including the backups, is lost.

This post outlines a practical implementation of the widely accepted **3-2-1 backup strategy** to ensure robust data integrity and disaster recovery capabilities.

## 2. The 3-2-1 Backup Principle

The 3-2-1 rule is a simple, effective framework for building a resilient backup system. It states that you should:

*   Have at least **THREE** copies of your data.
*   Store the copies on **TWO** different media.
*   Keep **ONE** of these copies off-site.

This strategy protects against a wide range of data loss scenarios.

## 3. A Practical Implementation

Here is a tiered approach to implementing the 3-2-1 strategy, using a combination of local and cloud resources.

### Tier 1: The Primary Copy (Local NAS with RAID)

The first step is to centralize the primary, "live" copy of the data on a reliable local device. A Network Attached Storage (NAS) device is ideal for this.

*   **Hardware:** A dedicated NAS unit with at least two drive bays.
*   **Storage Medium:** Two or more hard drives.
*   **Redundancy:** The drives should be configured in a **RAID 1 (mirroring)** array. In this configuration, all data written to the first drive is simultaneously written to the second. This is not a backup, but rather a form of real-time hardware redundancy. If one drive fails, the NAS continues to operate without data loss, and the failed drive can be replaced.

This setup provides high availability and protects against the most common failure scenario: a single hard drive malfunction. This constitutes our **first copy** on our **first medium**.

### Tier 2: The Second Copy (Local Snapshot or Backup)

While RAID protects against a drive failure, it does not protect against accidental file deletion, corruption, or ransomware. If a file is deleted from the RAID array, it is deleted from both drives simultaneously.

Therefore, a true backup is needed. This can be achieved by:
*   **Scheduled Snapshots:** Many NAS operating systems support creating regular, point-in-time snapshots of the file system.
*   **Local Backup:** A script (e.g., using a tool like `rsync` or `duplicity`) that runs on a schedule to copy the data from the primary storage volume to a separate volume or an attached USB drive.

This local backup is our **second copy** of the data, still on the **first medium** (the NAS device itself or a drive connected to it).

### Tier 3: The Third Copy (Off-Site Cloud Storage)

To satisfy the final, critical component of the 3-2-1 rule, a copy of the data must be stored in a different physical location. This protects against localized disasters like fire, flood, or theft.

*   **Storage Medium:** Cloud-based object storage (e.g., AWS S3 Glacier, Backblaze B2).
*   **Process:** A scheduled, automated task that encrypts the local backup and uploads it to the off-site storage provider. The requirements for this off-site copy are typically:
    *   **High Durability:** The service should guarantee the integrity of the stored data.
    *   **Low Cost:** Since this data is for archival and disaster recovery, access speed is less important than storage cost.
    *   **Security:** The backup should be encrypted *before* it leaves the local network.

This off-site backup is our **third copy** on a **second medium** (the cloud provider's infrastructure), satisfying all conditions of the 3-2-1 rule.

## 4. Conclusion

By architecting a multi-tiered data protection plan, we move from a fragile, single-point-of-failure system to a resilient and reliable one. The 3-2-1 strategy, implemented with a local NAS for redundancy and performance and an off-site cloud backup for disaster recovery, provides comprehensive protection for critical data. This demonstrates a strategic approach to system administration, prioritizing data integrity and business continuity.



## 1. Objective: Secure Remote Access to a Home Network

After setting up a [local network attached storage (NAS)](/blogs/building-a-raspberry-pi-nas), the next logical step is to enable secure remote access to it and other home network resources. Exposing a file share directly to the internet is a significant security risk. A far more secure solution is to create a Virtual Private Network (VPN).

This guide details the process of configuring a Raspberry Pi to act as a robust OpenVPN server. This allows for the creation of an encrypted tunnel from any client device (a laptop, phone, etc.) back to the home network, effectively placing the remote device on the local LAN.

![](/images/blogs/image.15.png)

## 2. Pre-Configuration: Network Groundwork

Before installing OpenVPN, several networking prerequisites must be met to ensure the server is stable and reachable from the internet.

### A. Dynamic DNS (DDNS) for a Dynamic IP

Most residential internet service providers assign dynamic IP addresses that change periodically. To provide a consistent endpoint for the VPN, a Dynamic DNS service is essential. DDNS maps a static hostname (e.g., `my-home-vpn.noip.com`) to your changing public IP address.

I used a free service from [NoIP](https://my.noip.com/), which requires running a small client on the Raspberry Pi. This **Dynamic Update Client (DUC)** periodically checks the public IP and updates the DNS record if it has changed.

### B. Static Local IP for the Raspberry Pi

The VPN server itself needs a predictable IP address on the *local* network. This is crucial for setting up port forwarding. I configured a static IP for the Pi by editing the netplan configuration file in `/etc/netplan/`, ensuring it would not change on reboot.

### C. Port Forwarding on the Router

To allow incoming VPN connections, a port forwarding rule must be configured on the home router. This rule directs all traffic arriving on a specific port from the internet to the static local IP of the Raspberry Pi.

*   **Service:** OpenVPN
*   **Protocol:** UDP (preferred for VPNs)
*   **Port:** 1194 (the standard for OpenVPN)
*   **Destination IP:** The static IP of the Raspberry Pi.

## 3. Step 1: OpenVPN Server Installation and Configuration

With the network prepared, we can now set up the OpenVPN server.

### A. Enable IP Forwarding

A VPN server must be able to route traffic between networks (the public internet and the private LAN). This requires enabling IP forwarding in the Linux kernel. This is done by uncommenting the `net.ipv4.ip_forward=1` line in `/etc/sysctl.conf` and applying the change with `sudo sysctl -p`.

### B. Public Key Infrastructure (PKI) with Easy-RSA

OpenVPN uses a Public Key Infrastructure (PKI) to manage authentication and encryption. The `easy-rsa` tool simplifies the creation of the necessary certificates and keys.

1.  **Initialize PKI:** ` ./easyrsa init-pki`
2.  **Build Certificate Authority (CA):** `./easyrsa build-ca`
3.  **Generate Server Certificate & Key:** `./easyrsa build-server-full server nopass`
4.  **Generate Diffie-Hellman Parameters:** `./easyrsa gen-dh`
5.  **Generate TLS Auth Key:** `openvpn --genkey --secret ta.key`

This process creates a CA that acts as the root of trust, along with a unique certificate/key pair for the server.

![](/images/blogs/image.16.png)
*Generating Diffie-Hellman parameters, a critical step for secure key exchange.*

### C. Server Configuration (`server.conf`)

The main OpenVPN configuration file dictates the server's behavior. Starting with the sample `server.conf` file, I made the following key changes:

*   **Certificate Paths:** Pointed to the newly generated `ca.crt`, `server.crt`, `server.key`, `dh.pem`, and `ta.key` files.
*   **VPN Subnet:** Defined the virtual network for VPN clients (e.g., `server 10.8.0.0 255.255.255.0`). This should be a different subnet from the local LAN.
*   **Pushing Routes:** To allow VPN clients to access the entire home network, I added the line `push "route 192.168.1.0 255.255.255.0"` (replacing the IP with my home network's subnet).
*   **Static Route:** On my home router, I added a static route to direct all traffic destined for the VPN subnet (`10.8.0.0/24`) to the Raspberry Pi's static IP. This ensures two-way communication.

Finally, I configured the OpenVPN service to start automatically on boot using `systemd` or a simple `@reboot` cron job.

## 4. Step 2: Client Configuration

For each device that needs to connect to the VPN, a unique client certificate and key pair must be generated.

1.  **Generate Client Certificate & Key:** `./easyrsa build-client-full my-laptop nopass`
2.  **Create `.ovpn` Profile:** A client configuration file (`.ovpn`) is created, specifying the DDNS hostname, port, and paths to its certificate and key. For portability, the contents of the `ca.crt`, `my-laptop.crt`, and `my-laptop.key` can be embedded directly into the `.ovpn` file.

This profile can then be imported into any OpenVPN client, such as OpenVPN Connect on Windows or mobile devices.

## 5. Conclusion

This project successfully established a secure and reliable personal VPN, enabling encrypted remote access to my home network resources from anywhere. It serves as a practical application of fundamental networking concepts, including DNS, IP routing, and public key cryptography, demonstrating the power of a simple Raspberry Pi in building robust, self-hosted infrastructure.



## 1. Objective: A Personal, Low-Cost File Server

Cloud storage is convenient, but for bulk local file storage and sharing, a personal Network Attached Storage (NAS) device offers greater control, privacy, and speed. This guide provides a technical walkthrough of how to build a cost-effective NAS using a Raspberry Pi and an external USB hard drive.

The goal is to create a centralized file server on a home network that is accessible from other computers, behaving like a standard Windows network share. We will use **Samba**, the standard Windows interoperability suite of programs for Linux, to achieve this.

This project is ideal for anyone looking to practice Linux system administration and networking fundamentals.

## 2. Prerequisites

*   **Hardware:**
    *   A Raspberry Pi (any model with an Ethernet port will work).
    *   An SD card with Ubuntu Server 20.04 LTS (or a similar Debian-based OS) installed.
    *   An external USB hard drive.
*   **Software:**
    *   SSH access to the Raspberry Pi.
    *   Basic familiarity with the Linux command line.

## 3. Step 1: Mounting the External Hard Drive

The first step is to make the external storage permanently available to the Raspberry Pi's operating system.

### A. Identifying the Drive

After connecting the USB drive, we need to identify its device name. The `lsblk` (list block devices) command provides a clear overview of all connected storage.

```bash
lsblk
```
![](/images/blogs/lsblk.png)
*In this example, the 1TB drive is identified as `/dev/sda`, with the primary partition being `/dev/sda1`.*

### B. Ensuring a Persistent Mount Point

Mounting the drive directly with `sudo mount /dev/sda1 /mnt/external_drive` is temporary and will not survive a reboot. To ensure the drive is automatically mounted on startup, we must edit the file system table (`/etc/fstab`).

Using the device's unique identifier (UUID) is the most reliable way to reference the drive in `fstab`. First, find the UUID:

```bash
ls -l /dev/disk/by-uuid/
```
![](/images/blogs/uuid.png)

Next, create a mount point and grant appropriate permissions:
```bash
sudo mkdir /mnt/external_drive
sudo chown -R pi:pi /mnt/external_drive # Or your user/group
```

Finally, add the following line to the end of `/etc/fstab`, replacing `YOUR_UUID_HERE` with the actual UUID of your drive's partition. I formatted my drive to `ext4` for native Linux compatibility.

```
# /etc/fstab
UUID=YOUR_UUID_HERE /mnt/external_drive ext4 defaults,auto,users,rw,nofail 0 0
```
After saving the file, run `sudo mount -a` to mount all drives listed in `fstab` and confirm there are no errors.

## 4. Step 2: Installing and Configuring Samba

With the storage in place, the next step is to install and configure the Samba server software.

```bash
sudo apt update
sudo apt install samba
```

Samba's configuration is managed in the `/etc/samba/smb.conf` file. Here, we can define different "shares"—folders that will be accessible over the network.

First, create the directories on the external drive that you wish to share.
```bash
mkdir /mnt/external_drive/public
mkdir /mnt/external_drive/private_share
```

Next, open `/etc/samba/smb.conf` and add share definitions at the end of the file. Below is an example configuration that creates a public, guest-accessible share and a private, user-restricted share.

```ini
# /etc/samba/smb.conf

[Public Share]
path = /mnt/external_drive/public
browsable = yes
writable = yes
guest ok = yes
read only = no

[Private Share]
path = /mnt/external_drive/private_share
valid users = @your_user_group # Or a specific user
browsable = yes
writable = yes
guest ok = no
read only = no
```

## 5. Step 3: User Management and Finalization

For private shares, you must create Samba users. These are separate from Linux system users, though they must be linked to an existing system user.

```bash
# Add a new system user (if they don't exist)
sudo useradd myuser -m -G users

# Create a Samba password for that user
sudo smbpasswd -a myuser
```

Finally, restart the Samba services to apply all the configuration changes:
```bash
sudo systemctl restart smbd.service
sudo systemctl restart nmbd.service
```

## 6. Conclusion

Your Raspberry Pi is now functioning as a NAS. You can access the shares from a Windows machine by navigating to `\\<raspberry_pi_ip_address>` in the File Explorer, or by using the appropriate SMB client on macOS or other Linux machines.

This project successfully demonstrates how to configure a reliable, low-cost personal file server, providing a practical foundation in Linux storage management and network file sharing protocols.



## 1. The Problem: The Prototyping Bottleneck

During the development of a physical card game, our team established the core game mechanics and compiled all card data—names, descriptions, types, and abilities—into a master spreadsheet (CSV). We also had a standardized card layout.

The next step was to create physical prototypes for playtesting. The initial workflow was entirely manual:
1.  Open a card template in GIMP.
2.  Copy and paste the text for a single card from the spreadsheet.
3.  Export the card as an image.
4.  Repeat for every card in the set.
5.  Manually arrange all card images onto a single sheet for printing.

This process was a significant bottleneck. After creating just two cards, it was clear this approach was unsustainable due to three main factors:
*   **Inefficiency:** The workflow was incredibly time-consuming and tedious, involving repetitive manual tasks.
*   **Inconsistency:** Manual editing inevitably leads to minor inconsistencies in text placement, font sizes, and layout, requiring rigorous quality checking.
*   **Iteration Friction:** Any change to a card's text or stats required finding the correct file, re-editing it, and re-exporting, discouraging rapid iteration and balancing.

## 2. The Solution: A Data-Driven Asset Pipeline

To solve this, I developed a custom command-line tool in C# that automates the entire card generation process. The tool reads the master CSV file, programmatically generates a high-resolution image for each card, and then arranges them onto print-ready sheets.

![](/images/blogs/PotatoCardGen.gif)
*Demonstration of the C# tool generating card images from data.*

### Technical Implementation

The core of the application leverages the `System.Drawing` library (now available in the `System.Drawing.Common` NuGet package for modern .NET) to perform image manipulation.

**The Workflow:**
1.  **Data Ingestion:** The program parses the master `card_data.csv` file, which contains all the text and references to associated image assets (like icons).
2.  **Canvas Creation:** For each row in the CSV, a new `Bitmap` object is created in memory to serve as the canvas for the card.
3.  **Dynamic Rendering:** A `Graphics` object is created from the `Bitmap`, providing a suite of drawing methods (`FillRectangle`, `DrawString`, `DrawImage`) to render the card's components.
4.  **Image Composition:** The tool draws each element onto the canvas in layers: background, header panel, icons, title text, and description text, all positioned according to predefined layout rules.
5.  **Image Export:** Once a card is fully rendered, the `Bitmap` is saved to disk as a `.png` file.
6.  **Print Sheet Assembly:** After all individual card images are generated, the tool creates a larger canvas and arranges the required number of each card onto a final print sheet, ready for use.

### Code Snippet: Drawing a Card Header

The following C# snippet demonstrates how the `Graphics` class is used to draw the colored header panel and an icon onto the card canvas.

```csharp
using System.Drawing;
using System.Drawing.Imaging;

// Define card dimensions and colors
const int CARD_WIDTH_PIXELS = 825;
const int CARD_HEIGHT_PIXELS = 1125;
Color BACKGROUND_COLOR = Color.FromArgb(211, 211, 211);

// Create a blank canvas for a single card
using Bitmap canvas = new Bitmap(CARD_WIDTH_PIXELS, CARD_HEIGHT_PIXELS);
using Graphics marker = Graphics.FromImage(canvas);

// Set rendering quality
marker.SmoothingMode = System.Drawing.Drawing2D.SmoothingMode.AntiAlias;
marker.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAliasGridFit;

// Draw the header panel
using Brush panelBrush = new SolidBrush(BACKGROUND_COLOR);
Rectangle headerPanel = new Rectangle(0, 0, CARD_WIDTH_PIXELS, 150);
marker.FillRectangle(panelBrush, headerPanel);

// Draw the card type icon onto the header
string iconPath = "path/to/icon.png";
using Image cardTypeIcon = Bitmap.FromFile(iconPath);
Rectangle iconRect = new Rectangle(25, 25, 100, 100);
marker.DrawImage(cardTypeIcon, iconRect);

// ... additional drawing logic for text, etc. ...

// Save the final card image
canvas.Save("output/card_name.png", ImageFormat.Png);
```

## 3. The Results: A Transformed Workflow

The implementation of this tool had a transformative impact on our development process:
*   **Efficiency Gains:** Card generation time was reduced from hours of manual work to seconds of automated processing.
*   **Guaranteed Consistency:** All cards are generated from the same code and template, ensuring perfect consistency across the entire set.
*   **Frictionless Iteration:** Balancing and text changes are now as simple as editing a cell in the master CSV file and re-running the tool. This enabled rapid playtesting and refinement cycles.
*   **Single Source of Truth:** The CSV file became the definitive source for all card data, simplifying project management.

This project is a clear example of how a small investment in creating a custom development tool can yield massive returns in productivity and quality, turning a tedious manual task into a streamlined, automated pipeline.



## The Challenge: Automating Chat Interaction

During a period of Twitch platform instability, I discovered that its chat system is built on the Internet Relay Chat (IRC) protocol. This realization opened a door for automation. By connecting directly to Twitch's IRC servers, I could create a bot to interact with chat channels, independent of the web interface.

My initial goal was simple: automatically greet new users who joined a chat. This post details the journey from a simple client-side plugin to a robust, headless Ruby application running on a Raspberry Pi.

## Step 1: Understanding the Connection

Connecting to Twitch IRC is straightforward. The official documentation provides the necessary details:
*   **Server:** `irc.chat.twitch.tv`
*   **Port:** `6697` (for SSL)
*   **Authentication:** OAuth token (which can be securely obtained from the network traffic of your browser's developer tools while logged into Twitch).

Using a standard IRC client like [HexChat](https://hexchat.github.io/), I could join any channel (e.g., `#channelname`) and see raw IRC events, including user `JOIN` messages, which are normally hidden in the standard Twitch UI.

![](/images/blogs/TwitchIRC.png)

## Step 2: Proof of Concept with a HexChat Plugin

HexChat supports scripting in Lua, which was perfect for a quick prototype. The API provides a `hexchat.hook_print("Join", on_join)` function, which allows you to execute a callback whenever a "Join" event occurs.

My first script had two key functions:
1.  **`on_join(info)`:** This function would trigger when a user joined, extract their nickname, and send a greeting message to the channel.
2.  **Remembering Users:** To avoid spamming users who frequently reconnect, the script needed to track who it had already greeted. I implemented a simple file-based memory system, creating a file like `channel_username.mem` for each user greeted.

Here is a snippet of the initial Lua proof of concept:

```lua
hexchat.register("auto-greeter", "0.1", "Welcomes new members")

-- A simple file-based check to see if we've met the user before
local function file_exists(name)
   local f=io.open(name,"r")
   if f~=nil then io.close(f) return true else return false end
end

local function on_join(info)
   local nick = info[1]
   local chan = info[2]
   local memory_file = "C:\\Path\\To\\HexChat\\" .. chan .. "_" .. nick .. ".mem"

   if file_exists(memory_file) == false then
      -- Create the memory file and send a greeting
      touch_file(memory_file)
      hexchat.command("MSG " .. chan .. " " .. "Welcome, " .. nick .. "!")
   end
   return hexchat.EAT_NONE
end

hexchat.hook_print("Join", on_join)
```

This worked, but it had limitations. It was dependent on the HexChat client, and Lua's limited file system support made more complex logic difficult. It was time to build a proper, standalone application.

## Step 3: Building a Headless Bot in Ruby

I chose Ruby for its strong networking libraries and my familiarity with the language. The goal was to create a "headless" bot that could run on a server (like a Raspberry Pi) without a GUI.

This approach offered several advantages:
*   **Independence:** No longer reliant on a specific IRC client.
*   **Full Control:** Direct manipulation of the IRC protocol.
*   **24/7 Operation:** The bot could be containerized and run continuously.

The Ruby script connects to the Twitch IRC server using a standard TCP socket. It handles the initial authentication (`PASS` and `NICK` commands) and then enters a loop to read messages from the server.

### Evolving the Logic

Moving to a more powerful language allowed for significant improvements. Based on feedback that greeting "lurkers" (users who don't chat) could be intrusive, I changed the core logic.

*   **Trigger on First Message, Not Join:** Instead of hooking the `JOIN` event, the bot now listens for `PRIVMSG` (a user message). It only greets a user after they've sent their first message in a session.
*   **Smarter Memory:** The file-based memory system was enhanced. The bot now tracks the timestamp of the last interaction, allowing it to use different greeting messages for new users versus returning users.

The core of the Ruby bot is built using the Cinch IRC library, which simplifies connecting to the server and handling events. The main logic is contained within a `run_bot.rb` script.

```ruby
require 'cinch'
require_relative 'lib/helpers.rb'

# --- Configuration ---
username = get_arg(0) # Bot's Twitch username
password = get_arg(1) # Bot's OAuth token
input_channels = read_config("./channels.txt")
input_greetings = read_config("./greetings.txt")
input_return_greetings = read_config("./return_greetings.txt")

# --- Bot Setup ---
bot = Cinch::Bot.new do
  configure do |c|
    c.server = "irc.chat.twitch.tv"
    c.port = 6697
    c.ssl.use = true
    c.nick = username
    c.password = "oauth:#{password}"
    c.channels = input_channels
  end

  # Request Twitch-specific capabilities
  on :connect do
    bot.irc.send("CAP REQ :twitch.tv/membership")
  end

  # --- Main Logic: Greeting Users ---
  on :message do |m|
    # Don't greet self or the channel bot
    next if m.user.nick == bot.nick || m.user.nick == m.channel.name[1..-1]

    memory_file = "met/#{m.channel.name}/#{m.user.nick}.mem"
    now = Time.now

    # Check if we've greeted this user recently
    if File.exist?(memory_file)
      last_greeted_time = File.mtime(memory_file)
      # Only greet if it's been more than 12 hours
      if now > last_greeted_time + (12 * 60 * 60)
        m.reply "Welcome back, #{m.user.nick}! #{input_return_greetings.sample}"
        FileUtils.touch(memory_file) # Update timestamp
      end
    else
      # First time greeting, create the memory file
      FileUtils.mkdir_p(File.dirname(memory_file))
      FileUtils.touch(memory_file)
      m.reply "Welcome, #{m.user.nick}! #{input_greetings.sample}"
    end
  end
end

bot.start
```

## Conclusion

This project was a fantastic exercise in practical automation. It started with simple curiosity and evolved from a basic client plugin into a standalone, headless application. By moving to Ruby, I gained greater control and flexibility, allowing for more nuanced and respectful bot behavior. The final bot now runs quietly on a Raspberry Pi, a testament to the power of understanding the protocols that underpin the web services we use every day.

You can find the source code for the Ruby bot on [my GitHub](https://github.com/RGonzalezTechTips/Simple-Ruby-IRC-Bot).

Raul G.

Blog Posts

Latest Blog Post

Architecting a reliable Godot 4 Multiplayer Lobby

All Blog Posts

Architecting a reliable Godot 4 Multiplayer Lobby

Case Study: Modernizing a Community CI/CD Tool

Case Study: A Game Server with Discord Bot Integrations

Case Study: Migrating a Website to a Serverless AWS Stack

Architecting a Flexible Interaction System in Godot

Postmortem: Lessons from a Solo Game Dev Prototype

Auto-Connecting OpenVPN on Boot in a Windows AD Environment

A Guide to the 3-2-1 Backup Strategy for Data Integrity

Hosting a Secure VPN on a Raspberry Pi with OpenVPN

Building a Raspberry Pi NAS with Samba

Automating Card Game Prototyping with a C# Image Tool

Building a Headless Twitch Chat Bot with Ruby and IRC