allejo.io | interstellar space pirate extraordinaire

How and why I jailbroke my Kindle

2025-07-14T08:00:00+00:00

For years, I had been searching for the "perfect e-ink reader" that met all of my niche needs and wants. I wanted something with integration to calibre, the ability to download and read RSS feeds, and, lastly, the ability to connect to cloud storage, such as Google Drive, where I host my PDFs. These seem like a niche set of features, and honestly, they are. However, this is what I've always wanted. I conducted my research and evaluated numerous e-ink readers, including Boox, Kobo, the new Kindle, Nook, ReMarkable, and others. None of them checked all the boxes, and all came with extreme vendor lock-in or had virtually no developer community behind them. Sure, I've got an iPad that can accomplish all those features and more, but it has a lot more functionality than I need when I want to read without distractions.

I recently discovered the Kindle jailbreaking community and was reminded of my teen years when I was active in the iOS jailbreaking community. The level of freedom I had over my device at the time was something I would love to have over my Kindle. With Amazon recently running a big book sale that "coincidentally" overlapped with Independent Bookstore Day, I decided it was time to say "fuck you" to Amazon and part ways as much as I can.

Why am I jailbreaking my Kindle?

I have recently worked long hours organizing all my ebooks into a single library using Calibre, with the goal of eventually syncing them to my Kindle. Here's the tricky part, for years, I had been buying ebooks from Amazon, and while they did make the ecosystem incredibly user-friendly for the majority of the population, I felt limited due to the following:

As of February 26, 2025, Amazon has discontinued support for the "Download & Transfer via USB" functionality. This means it is now significantly more tedious for you to download copies of the ebooks you have bought. In the past, I have had Amazon delist ebooks from their online stores, and as a result, I lost access to them on my Kindle, as I can no longer search for them. Thankfully, I was in the habit of always downloading a copy of those ebooks, but what if I hadn't? I might have lost that digital book even though I bought it.
I never thought I would be writing this, but with the direction my country, the United States, is heading regarding censorship, I did not want to remain at the mercy of Amazon to dictate which books I've purchased, and still be allowed to read.
The only way I can transfer books to my Kindle wirelessly is by emailing the file to my Kindle email address, which Amazon manages. What's stopping Amazon from censoring the books I send to them to deliver to my Kindle?
My Kindle Paperwhite, 3rd generation, from 2015, is considered "end of life," meaning I no longer receive updates from Amazon. According to Amazon, my Kindle is considered no different from a paperweight. Why would I trade in, my perfectly functional and in good condition device for a new device that has even more restrictions placed on it? It's wasteful consumerism. If Amazon has stopped developing for my Kindle, let's turn to the open source community of nerds that hasn't.

Fuck Amazon! Let's jailbreak my 7th generation 2015 Kindle Paperwhite (aka PW3).

The Jailbreaking Process

First off, the jailbreaking process is nowhere near as simple as it was in my iOS days, where you could download an app on your computer, press a single button, and wait. That's not to say it's difficult or impossible; it's just a more involved process. A lot of very smart nerds who share the same sentiment about breathing new life into their abandoned devices have invested considerable effort in simplifying the process as much as possible.

Thank you to the awesome community behind Kindle Modding for writing all the tutorials and documentation I used to jailbreak my Kindle. This would not have been possible without HackerDude's WinterBreak exploit that I was able to get working.

The Prerequisites

A computer; it's not possible to jailbreak your Kindle just from the device itself
Your Kindle must be registered with Amazon (unfortunately)
You must have a saved Wi-Fi connection on your Kindle, and be ready to connect to that Wi-Fi during the jailbreak process

Run the Jailbreak Exploit

The first step is to run an exploit, which allows us to remove security restrictions on the Kindle; this is known as "jailbreaking."

Download the latest release of the WinterBreak jailbreak on your computer.
Turn on airplane mode on your Kindle.
Reboot your Kindle.
After rebooting, connect the Kindle to the computer via USB. Extract WinterBreak and copy over the contents onto the Kindle (including the hidden dot files!). Replace any files that may already exist.
Eject your Kindle from the computer.
Open the Kindle Store by clicking on the cart icon. It'll prompt you to turn off Airplane mode, do it. Once the store loads, the Mesquito hack will be displayed. Click to run it.

The Kindle Store serves as our environment for executing code, so we run the Mesquito exploit from here.
Wait for a few seconds, and then console text will appear in the upper left corner of the display. At this point, turn airplane mode back on and install the hotfix to persist this jailbreak across reboots.

When the jailbreak process is complete, the top left of your Kindle will display Terminal-like log message.

Persisting the Jailbreak (aka "Installing the Hotfix")

The next step is to persist this jailbreak across reboots and updates; a Kindle update referred to as a "hotfix" is needed to accomplish this.

Download the update .bin file from GitHub, this file is what's known as the "hotfix."
Plug in the Kindle and copy the .bin file to the device's root directory. If there are any other .bin files on the device already, delete them first.
Go to your Kindle settings, then click the three-dot menu, and select "Update your Kindle." Confirm the installation.

From your Kindle settings, you will apply the hotfix as an "update" to your Kindle software.
After the Kindle has rebooted, the hotfix is now installed and needs to be executed on the device. A new "ebook" is displayed in your device's library called "Run Hotfix." Open that book to run the process.
Do not delete the hotfix ebook, it is necessary to run it every time there's an update.

Install KUAL and MRPI

Now that our Kindle is fully jailbroken, we can run whatever code or applications we want. Similarly to how the hotfix in the previous step created a fake ebook that, when opened, executed code, we need to do the same for our other applications so that we can launch them from the Kindle UI. This is where the Kindle Unified Application Launcher, or KUAL, comes in to solve that need.

Download KUAL for devices released in 2012 or after, or KUAL for legacy devices (pre-2012).
Download the MobileRead Package Installer (MRPI) to simplify the installation of update packages (remember the .bin file from the previous step?).
Connect your Kindle to your computer.
Extract the MRPI contents and copy over/merge the extensions and mrpackages folders to your Kindle.
Copy over the KUAL .bin file to the root of the device.
Eject and unplug your Kindle.
In the Kindle's search bar, type ;log mrpi.
Go to your Kindle settings, then click the three dot menu, and select "Update your Kindle." Confirm the installation.
After your Kindle reboots, a KUAL ebook should be located in your library.

Disable OTA Updates

My Kindle Paperwhite 3rd gen is EOL and no longer receives updates, but let's disable OTA anyway to be safe. My Kindle is stuck at firmware 5.16.2.1.1, so I need to install renameotabin.

Download renameotabin.
Connect the Kindle to your computer and copy the renameotabin folder into the extensions folder.
Eject and unplug the Kindle.
Open the KUAL ebook and select "Rename OTA Binaries" from the menu. Then, proceed to select "Rename."
1. If you need to restore, downgrade, or otherwise manage your Kindle through official methods, select Restore before proceeding.

Restoring the Store

I'm not sure how I feel about having the Kindle Store enabled again, but I've re-enabled its access, just in case I need it. I may turn it off at a later point.

Delete .active_content_sandbox from the root of the device.
Eject and unplug.
Reboot your device.

Installing KOReader

KOReader is a replacement for Kindle's default e-Reader software, and honestly, it has so much more. This is the biggest reason why I jailbroke my Kindle.

Download the latest version of KOReader from GitHub
If your Kindle was released before 2012, use the "legacy" Kindle download. Otherwise, download the non-"legacy" version.
Connect the Kindle to the computer.
Extract the contents of the KOReader archive and copy/merge over all the folders onto the Kindle's root.
Launch KOReader from KUAL; prefer to use "Start KOReader" because the "no framework" version is largely intended for older devices. The ASAP variant is a faster startup time for KOReader, but I see no need to use it since it loads fast for me.

Setting Up SSH

I'm trying to avoid having a micro-USB cable on my desk; I already have one at my charging station. Every other device that's on my desk supports either wireless charging or USB-C; I like to avoid having too many cables. I enabled SSH on my Kindle so that I could mount it wirelessly on my Mac; i.e., I can drag and drop files from my SFTP client wirelessly.

Within KOReader, I navigate to the gear icon in the top menu bar, then select Network, followed by SSH Server.

In KOReader's Gear menu, select the "Network" submenu that is the third item from the top.

Within the Network menu, select the "SSH server" submenu that is the last item of the menu.

I'm setting up my SSH key on the Kindle so that I can connect to it securely.

I first need to temporarily enable "Login without password (DANGEROUS)" on my Kindle. This will allow me to connect to the Kindle via SSH with a blank password.
Then, I will start the SSH server by clicking on the "SSH Server" menu item. You will get a pop-up on your Kindle that displays its IP address; I need it for the next step.

When the SSH server has started, you'll receive a success notification with two bits of important information: the Kindle's IP address and KOReader's SSH port.
I can now connect via SSH. The connection details are as follows,
- Host: Your Kindle's IP address from step 2, for me, it was 192.168.12.120.
- Username: root
- Password: <leave empty>

My SSH command looked like so,

$ ssh root@192.168.12.120 -p 2222
#################################################
#  N O T I C E  *  N O T I C E  *  N O T I C E  #
#################################################
Rootfs is mounted read-only. Invoke mntroot rw to
switch back to a writable rootfs.
#################################################
[root@kindle root]# mntroot rw

Upon connecting, I'm greeted by this notice that essentially tells me, "consider your current session as read-only, if you want to make edits to any files, (which we do), run this command." I want to be able to save my public key on the Kindle so that we can use it to SSH in; therefore we need to make the filesystem writable.

# mntroot rw
system: I mntroot:def:Making root filesystem writeable

Now I need to find my Kindle's authorized_keys file, which is located at, /mnt/us/koreader/settings/SSH/authorized_keys. Like most light-weight systems, the only text editor available is vi so be sure to know how to exit once you're done.

Paste your public key into your authorized_keys and exit your SSH session. Go back to your Kindle and shut down your SSH server. Earlier, I enabled "Login without password." Now, it's time for me to turn it off, and I should be able to log in with my SSH key.

To verify that updating my authorized_keys worked correctly, I'll add a -v to my SSH command and read the logs of which public key is accepted by my Kindle (I have several keys on my computer).

$ ssh root@192.168.12.120 -p 2222 -v

... lots of output ...

debug1: Offering public key: /Users/allejo/.ssh/id_ed25519 ED25519 SHA256:9S2ld7G9EZXqIbqXKvosAKA74Xj1rDaOP9Gpx4pvdIQ
debug1: Server accepts key: /Users/allejo/.ssh/id_ed25519 ED25519 SHA256:9S2ld7G9EZXqIbqXKvosAKA74Xj1rDaOP9Gpx4pvdIQ
Enter passphrase for key '/Users/allejo/.ssh/id_ed25519':

The "Server accepts key:" line is what we're looking for. This means that my Kindle recognizes my SSH key and will allow me to log in once I unlock my key. Now, I can use my favorite SFTP client to connect to my Kindle securely. If I want to see the equivalent of my Kindle's "root," i.e., the filesystem I see when I connect my Kindle to my computer with a micro-USB cable, that's mounted at /mnt/us/.

Screenshots

Another feature I was oddly excited for was the ability to take screenshots! Okay, so Kindles have been able to take screenshots since at least 2020, but it's such a bad experience. The gesture isn't tricky, but for the life of me, I cannot tap both corners at the same time. And let's say I do manage to do so by chance; the screen flashes white, and that's it. But you know what else that looks like? Your Kindle repainting its entire screen. There's no notification at all that my screenshot was successful.

But KOReader gets it right! Its default gesture for screenshots is a long one-finger diagonal swipe. I swipe from a top corner to its diagonal bottom corner, and I receive a notification that my screenshot was taken.

KOReader displays a notification when you successfully take a screenshot, confirming your action was recorded.

And since I can SFTP to my Kindle at any time, I can easily view those screenshots on my computer. And since KOReader provides a file browser, I can go find my screenshots at /mnt/us/koreader/screenshots/ and view them on my Kindle itself!

Add a Dictionary

My KOReader installation did not have a dictionary installed by default; I'm unsure if I configured it that way or if this is expected. There are two methods for installing dictionaries: through KOReader's top menu and by manually transferring dictionaries.

In KOReader, tap the magnifying glass icon to access the Search menu.

From the Search menu, select the "Settings" option to configure dictionary and search preferences.

The "Dictionary Settings" menu allows you to manage, download, and configure how dictionaries work in KOReader.

The first option is to install a dictionary from inside KOReader. Navigate to the Search menu (represented by a magnifying glass), then select Settings, and finally, Download Dictionaries. The annoying part about this method is that there are 20 pages worth of dictionaries that you need to flip through. "E" for "English" is early on in the alphabet, so it's on page 4 for me.

The "Download Dictionaries" submenu shows a paginated list of available dictionaries to install.

The English dictionary can be found on page 4 of the "Download Dictionaries" submenu.

Manually via SFTP (or wired)

My preferred approach is to download dictionary bundles manually and copy them to my Kindle via SFTP (or wired, if you prefer). The dictionaries I downloaded and installed are based on daily dumps from Wiktionary; I got the English-only dictionary and an English-Spanish dictionary.

English Dictionary from Wiktionary (i.e. dict-en-en.zip)
Bilingual Dictionaries from Wiktionary (i.e. wikdict-en-es.zip)

KOReader supports dictionaries that are in the StarDict format, which consists of extensions such as *.idx, *.ifo, or *.ifo.gz, as well as *.dict or *.dict.dz. The above links will download a ZIP file, respectively, that, when extracted, gives you folders with their StarDict files inside. Extracting these ZIP files gave me the dict-en-en and wikdict-en-es folders.

KOReader requires dictionaries to be stored in /mnt/us/koreader/data/dict (or /koreader/data/dict when connected with a cable). Each dictionary requires two levels of folders, so I created two folders to store my downloaded dictionary: "WikDict Bilingual" and "Ebook Reader Dict;" I then put wikdict-en-es and dict-en-en in those folders, respectively.

.
  |- GNU Collaborative International Dictionary of English
  |  |- gcide
  |  |  |- stardict.idx
  |  |  |- stardict.dict.dz
  |  |  |- stardict.syn
  |  |  |- stardict.ifo
  |  |  |- stardict.idx.oft
  |- WikDict Bilingual
  |  |- wikdict-en-es
  |  |  |- stardict.dict.dz
  |  |  |- stardict.idx
  |  |  |- stardict.ifo
  |  |  |- stardict.idx.oft
  |- Ebook Reader Dict
  |  |- dict-en-en
  |  |  |- dict-data.ifo
  |  |  |- dict-data.dict.dz
  |  |  |- dict-data.syn.dz
  |  |  |- res/
  |  |  |- dict-data.idx
  |  |  |- dict-data.idx.oft

After installing dictionaries, the data/dict/ folder looks like the file tree shown above. The "GNU Collaborative International Dictionary of English" folder was automatically created for me by KOReader when I installed the English dictionary through the KOReader UI (as discussed in the previous section).

The "Dictionary Management" menu allows you to view and manage all installed dictionaries on your Kindle.

Exiting KOReader

One important thing to note is that while KOReader is running, it is not possible to connect your Kindle to your computer using a USB cable and transfer data to it. For me, this isn't an issue since I've set up SSH, and I've been wanting the ability to manage my Kindle wirelessly from my desk.

Now, I may not need to exit KOReader to transfer any books to it, but it is helpful to know how to exit an application; I'm looking at you, Vim. Exiting KOReader will return me to my stock Kindle UI; this will turn off any of the features I mentioned, such as screenshots or SSH. The way I see it is KOReader is your enhanced "operating system" providing many useful services and integrations/apps. I intend on running KOReader 24/7 on my Kindle and treat it as a better OS.

Access the main menu by tapping the hamburger icon to find the Exit submenu.

Select "Exit" once more to close KOReader and return to the stock Kindle interface.

Click on the Main menu (the hamburger icon), then click on Exit, and choose Exit again to shut down KOReader entirely.

Next free weekend's task: integrating calibre

One of the most powerful features that I'm excited about is its wireless integration with calibre! My tags, genres, and collections—everything I've worked on—will finally integrate smoothly with my Kindle. Something Amazon would never support with its shit excuse for a library UI on its website or within its apps. However, I have yet to fully learn about this feature, and it will be a project for another weekend.

Being Promoted to Customer at Stack Overflow

2023-10-21T08:00:00+00:00

All good things must come to an end, am I right? And with Stack Overflow's second round of layoffs this past week, I figured I'd finally write something. My tenure at Stack Overflow ended prematurely. Unfortunately, I was affected by its May 2023 layoff, and truth be told, I was heartbroken. No workplace is ever perfect, but I loved working at Stack Overflow. I was proud of the impact I was making, an impact on the lives of millions of developers around the world. To say I was blindsided by the layoff is an understatement.

The night before I got laid off, I had just finished merging four different PRs that were the culmination of about three months' worth of my work to restructure the front-end codebase of Stack Overflow. Finally! I had gotten the first handful of reusable and accessible Stimulus components built, tested, shipped, and integrated with our build system. I had read stories about other companies having layoffs and their employees losing access to their work accounts overnight, but I never thought it would happen to me. I was wrong. Unlike some other companies, I at least met with my manager, who told me the news. After the meeting, I immediately sent one message to my team's channel saying I had fun working with them and that I had gotten laid off. I saw the "Jane Doe is typing..." message, and then Slack signed me out. That fucking hurt. I couldn't see what anybody responded. I couldn't say bye to my friends, some of whom don't have or aren't active on social media.

The Job Hunt

It is no secret that I loathe capitalism. If you're in tech, you probably know how awful the job market is right now, as with many other fields. This poor job market could have been avoided if more large companies hadn't done so much hiring to the point where they couldn't sustain themselves past the pandemic slowdown.

I like statistics, so as I've been applying to jobs, I've been doing my best to keep a spreadsheet of the jobs I've applied to, responses I've gotten, etc. At first, I thought it would be fun to keep track of these numbers, but now it's harming my mental health and self-confidence more than anything else.

Submitted ~400 applications
Received ~120 rejections
Never received a status update (aka ghosted) ~260 times
Got 15 interviews
- 4 rejections after interviewing
- Ghosted 11 times after interviewing (i.e., never heard back after interviewing; yes, I did try reaching out)

If you're a hiring manager that has interviewed someone and hasn't gotten back to them despite them directly emailing you: Go fuck yourself. It doesn't matter how many applicants you have or how busy you are; sending a quick, templated message of "Sorry, we're not going with you" is much better than ignoring folks who set time aside to interview with you. If you have too many applicants, then limit how many applications you can accept before a job automatically closes. Stop fucking wasting other people's time.

Things I'm Tired of Hearing

I have plenty of very kind and supportive folks in my life. While they all have good intentions, the most common things I've been told that I'm honestly tired of hearing are,

You're a great developer! It'll be easy for you to get another job.

Clearly, it's not been "easy" considering the stats above.

You should consider this a vacation and enjoy your time off!

There's a difference between taking a vacation and being unemployed. Being on vacation means you are still getting paid and have a job to return to after your vacation.

Have you been applying for jobs?

Yea, no shit.

I have complained about this before on social media, and I've had a few folks reach out to me to apologize, but honestly, I take no offense to it. I know folks mean well, but I'm just exhausted from hearing the same things repeatedly. That's all.

What am I up to now?

I'm currently doing some contracting work for the awesome folks at Compiler, catching up with some open source work, returning to the BZFlag community with gifts, and finishing my thesis! It's only taken me five months of being unemployed to finally improve my mental health slightly and start tackling life again. However, that doesn't mean I'd consider myself as being back on my feet. That will only happen once I have more security of being employed full-time with benefits and not worrying about what's next after a contract ends.

Oh, and I've also been shit posting on LinkedIn recently with a surprising amount of impressions. For someone who never posts on LinkedIn, I've been getting more activity lately than I have in years. So, follow me on LinkedIn to read up on my stupid posts that have a hint of professionalism. Or don't; I'm not your boss. I can't tell you what to do.

There's a lot more I would love to say and speak about related to Stack Overflow, but I'm legally prohibited from doing so; I needed that severance!

Joining Stack Overflow

2022-11-21T08:00:00+00:00

It’s been radio silence on my site for almost two years. Since my last post, I got hired by one of my dream companies: Stack Overflow. I have always enjoyed building tools to make the developer experience easier for everyone, so it should be no surprise that working at Stack Overflow has always been a dream of mine. I have actually applied to Stack Overflow twice in my life; the first time, I didn’t even make it to the phone screening. The second time, I got hired. If at first you don’t succeed, give up. Or something like that, right?

Leaving the Public Sector

Since I started working professionally at 19, I have always been working in the public sector: local government (City of Santa Monica) then state government (California State University, Northridge). I enjoyed it, I loved the thought of contributing to building things that would benefit the public and not be done for a profit. I loved working for a university because I wanted to build things for students and make their lives better. I had hired student developers and was mentoring them to build production level applications. Despite upper management thinking I was unreasonable for expecting good code from students, I had faith that with a bit of direction they’d be able to write clean code. Turns out, I was right. I felt like I was making a difference in the lives of others and I was ecstatic. But I wasn’t feeling fulfilled or appreciated.

Any time I put forward ideas to improve the lives of the student population, I’d get told that it wasn’t a priority. Employee appreciation and fun was in the form of seasonal parties where each employee would pitch in ~$20 so that we could have a budget. As a taxpayer-funded entity, we had to be mindful of how we spent our money. However, there was no shortage of sessions with “job coaches” for our directors to help them improve their management skills. We had monthly birthday celebrations with a giant cake from Costco, where we were reminded of the directors’ generousity by pitching in to get us this cake.

So I left.

Interviewing at Stack Overflow

Stack Overflow is incredibly open about its hiring process and following in that spirit, I’d like to talk about my experience. Firstly, my interviewing experience was incredibly nerve-racking at almost every step of the way and I’ll explain why.

The very first time I applied to Stack Overflow was on July 3rd, 2020 and I promptly received a rejection email on July 10, 2020. I got rejected in 7 days. Thank you for letting me know! There’s nothing worse than receiving a rejection email months after you even remember applying. I was disheartened by the rejection email but thankful they told me I had gotten rejected.
As I mentioned, it was my second time applying to Stack Overflow. I applied on January 1st, 2021. New year, new job? Am I right? Ha. Because the first time I applied I got an update on my application status after a week, I had hoped the same would be true this time around. A week passed. Two weeks. Three... I just assumed I had gotten rejected. It wasn’t until March 8th that I got an email from Stack Overflow apologizing that they hadn’t been able to process all their applications in a timely manner and that if I was still interested in applying, to click a link to resubmit. My dream company? Apologizing? Yes, of course I forgive you! (Sell-out, I know). On March 10th, a recruiter from Stack Overflow reached out to me asking to schedule an interview. It’s happening, y’all!
The initial screening happened and at this point, the recruiter asked me some basic questions about my experience, my salary expectations, what I was looking for, etc. The recruiter and I ended up bonding over the GIS Stack Exchange; what are the odds? But, I did it! I had an interview at my dream company! I was feeling pretty happy at this moment.
The recruiter reached out to schedule a code screen interview! AKA “the hiring manager interview” because as the name suggests, he became my manager. It started off being a terrifying interview as he asked me about an algorithm that I had never heard of. I guess he saw the panic in my face as he proceeded to tell me he hadn’t heard of it either until he joined Stack. He described to me what the algorithm had to do and then I proceeded to write the code. At the end of the interview, I felt pretty good with my implementation but of course, I had to confirm. So I rewrote my code and tested to see if it would work and... it didn’t! I was horrified. I was close but made a mistake with my logic and I thought I had failed that step of the interview.
You can imagine my surprise when I got an email from the recruiter telling me I had moved on to the next step and to schedule my Algorithm and Architecture interviews with Stack developers. After each of these interviews, I felt the exact same feeling where I thought I had failed each time because I would work through the problem a second time after the interview and see how I did. Each time, I made minor mistakes in my code and my solution would be off since during these interviews, we didn’t run the code I wrote (spoiler: I wrote my code in Google Docs). I was honestly expecting to receive an email from the recruiter thanking me for my time and better luck next time.
I couldn’t believe it. I had received an email from the recruiter asking to schedule an interview with a VP. Despite me making mistakes in my code during the interviews, I still passed and moved forward. This would turn out to be my last interview before I received an offer. In actuality, this wasn’t so much an interview than a casual chat with the VP about Stack Overflow as a company and what it’s like working there.

Then on April 13, 2021, I received an email from the recruiter. It was an update, “the fun kind.” It was an email to schedule a call for an official offer, which obviously, I accepted.

About the Interviews

A few months after getting hired, I was shadowing my colleagues performing interviews and shortly after, I was interviewing other candidates myself. The way interviews are done at Stack Overflow are a bit different from other companies, I feel. I’ve seen companies ask Leet Code style questions or CS heavy questions (e.g. invert a binary tree). Most statistics on the internet are made up but I think it’s safe to say that unless you’d be working on low-level stuff like a language/compiler, you’ll rarely ever need in-depth knowledge of algorithms that haven’t already been implemented in an existing library or language runtime. Asking these types of questions introduces a huge disadvantage to self-taught developers, career switchers, bootcamp participants, and many others that never had a college CS education.

So what’s different about the interviews we give at Stack? We focus largely on realistic problem solving; we give candidates real life scenarios and have them write code to solve those problems. For example, a completely hypothetical interview prompt we’d give is — given a CSV file you should write code that will accept the extracted contents, aggregate some stuff, and finally output the contents of the new data to standard out. In my opinion, it’s realistic problem solving rather than memorizing certain algorithms that you’ll never use in your day to day.

What’s it like?

Amazing and lots of fun. Despite being in open source for years, I am very early on in my professional career and still lack a lot of experience for things at the scale of Stack Overflow. Since starting there, I can honestly say that there hasn’t been a day where I haven’t learned something new. It’s an absolutely amazing feeling to have so many brilliant people be my coworkers, teachers, and mentors.

I started on the Community Products - Engagement team, which was originally tasked with maintaining the Stack Overflow Jobs board and Developer Story. We were later tasked with killing it, much to the disappointment of several in our community.

Recently, I have moved to the Community Enablement team, which focuses largely on building, improving, and managing moderator tools. The Stack Exchange network could not exist without the community members and its moderators keeping everything alive and in good shape. We’re a new team and I’m looking forward to the things that will be coming out of this team.

Wait, We Have Customers?

2020-09-13T08:00:00+00:00

I have never worked retail in my life and for that, I am very grateful. Trust me, with my sarcasm and attitude, you do not want me working in retail. If you work in retail, you have my full respect; I could never do what you do. Working on a college campus, something I see very often is that employees forget who we're working for and who our customers are.

For those of you who know me, I'm excruciatingly honest and rarely ever filter myself; this trait of mine has gotten me in trouble at work plenty of times. This post isn't meant to be philosophical but I believe we're in our current state because no one spoke up early on when important decisions were being made and things just became the norm.

Describing a College Campus

As much as I would love to air all of the dirty laundry I'm privy to about the college campus I work on, that's considered taboo. I'm sorry, let's call it "whistleblowing" instead. Sounds worse, am I right? Everyone has different opinions about what's ethical and what's not. Is telling someone that whistleblowing is the same as "career suicide" ethical? Depends on who you ask. But I digress.

The college campus I work at is huge; it's got enough employees to populate a small town. I'm a developer, so of course, I work for the IT department. But wait. Which one? Practically every department on campus has its own IT team and then, of course, we have the central IT department in charge of maintaining the core infrastructure for the campus (that's where I work). Our separate IT teams on campus work together as well as the "checks and balances" system of the US government: it's nice in theory but terrible in practice. Sorry, third graders, that was a spoiler.

Customers on a Campus

Who are the customers for a college campus? If you guessed, "students," then you're right! Actually, in theory, you're right. When it comes down to it, I genuinely do not believe that the employees of a college campus remember that students are our "customers." They're literally paying thousands of dollars and funding the salaries of employees and yet... They're not treated as customers? How does that make sense?

The battles students need to fight against the administration amazes me. Some students can get through their college careers with no problems but others, face a plethora of obstacles. Have you ever tried transferring credits between colleges? Let's say you're transferring from College A to College B. You are literally at the mercy of College B's discretion on whether or not College A's teachings live up to College B's standards. What happens if your credits are rejected? Then you have to take the classes again at College B.

But there are charts published by colleges stating which credits they will and will not accept!

Listen to yourself. Let that sink in. Colleges are literally publishing what they think about other college's coursework. This is a battle between colleges and students are caught in the middle of it. This is a fundamental problem with the education system not being standardized.

Those published charts are literally standardization of what is being taught. That's why colleges have those charts.

It's cute you think that. Have you ever read a syllabus at the beginning of a semester and thought to yourself, "wow! That sounds so cool! I'm going to learn so much in this class," but by the end of the semester, you realize that everything on the syllabus was either a lie or blown out of proportion?

It's these syllabi that are agreed upon between campuses. This is why making changes to them is very painful because they need to be "reevaluated" by other colleges and other colleges need to change their own syllabi to teach the same material or reject it and no longer accept transfer credits.

Why do people accept it as "the norm" for colleges treating their students like they don't matter? Students are the reason we are getting paid. We should not be making their lives incredibly difficult and wasting their time.

"Culture" is the word that every managerial figure loves to hear and boasts about. I agree that we have a culture on campus, however, I would add an adjective to it: toxic.

Why did I originally bring up working in IT and other IT teams on campus? One of the biggest problems I see is that people in IT forget that students are our customers. Well, not directly. The IT teams I'm talking about build and manage things for faculty and administration that then help those users provide services for students. This is how people forget we're ultimately serving students.

The vast majority of the tools I work on are intended to be used internally by campus employees to make their lives easier so that they can make things better for students. If you have ever worked with me or seen my work on GitHub, you probably know that I absolutely love building things in a modular way. Incredibly modular; but not a "dependency hell" type of modular either. Please don't question my judgment, that's what my parents are for. As an example of something modular that I've built, let's look at my "BZFlag Plug-in Starter" that consists of three separate projects:

aclovis: a library for generating C++ code via JavaScript. This project has enough interfaces where it can be expanded to generating other languages too if I wanted to.
bzfPluginGen: a library that uses aclovis to generate the source code for a BZFlag plug-in.
BZFlag Plug-in Starter: a React website that uses bzfPluginGen to let users generate plug-ins by clicking buttons.

All of these tools build on top of each other and can be expanded on their own! aclovis can be expanded to support other languages. bzfPluginGen can be updated to generate a new C++ syntax. BZFlag Plug-in Starter can be updated to have an entirely different design. It may seem like overkill but they all live in their own separate projects with a single purpose in mind. I have plenty more examples on GitHub but the point is, many of my tools at work are this modular.

There are plenty of tools that my colleagues have built as well that can be useful to other departments if shared! It's this type of sharing that is currently discouraged. Wait what? Dis-couraged? Yes. This is one of many reasons why I consider our current culture is toxic. We are forcing everyone to work in silos because nobody wants to take responsibility for maintaining shared tools.

If we release it to other teams and they find a bug, do we have to drop everything and fix it for them?

No! Who the hell makes those types of guarantees? Even Microsoft doesn't fix that one bug in Microsoft Excel that drives your industry insane. So why should you? You are not making any guarantees by sharing your code. What you are doing is saving other people time. In the future, their teams may work on a feature of a shared tool that you end up needing.

But what if people expect us to make guarantees?

Use an open source license! For example, the MIT license clearly states, 'THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED...' The open source world has got these things figured out already. Where have you been?

Wait. If everyone is using the same tool, doesn't that mean there are more people who can fix bugs? If someone wants a feature, doesn't that mean there are more people who can work on the feature? You mean, someone else has already laid out the foundation for a project and all you have to do is add this one small feature that you need and not spend weeks building the same thing from scratch?

(insert mind blown gif)

Yes! Yes! Yes! Share your code with other teams on campus and release it as inner source. Start a culture on your campus of sharing your code with other teams! Once you're comfortable with that, start sharing with other campuses! That's when you're ready for the big boy world of open source.

But Law is Scary!

Clearly, you have not seen the thousands of popular open source projects started by random users with absolutely no legal experience. I'm recommending you use an open source license because it's quick and easy. As I said, the open source world has got it figured out.

I'm not a lawyer. What do I know? Allow me to point you to Ben Balter's amazing post about open source licensing. If the average high schooler can create something on GitHub and open source it, I'm sure you can too. Developers should be focusing their time on developing new things, not worry about licensing, or reinventing the wheel.

Encourage developers to share. We love creating stuff but not stuff that's already been invented. Remember college employees, students are the reason you still have jobs; you should be building things for them in the most efficient way possible.

2019 Year-in-Review

2019-12-21T08:00:00+00:00

This year had a really rough start and had a bumpy ride everywhere in between due to personal problems. BUT! It’s okay, there’s a lot of other stuff that happened this year that made things interesting and enjoyable for me. Well, I’m sure a lot more stuff happened but these are the only things I remember or am willing to share.

Grad School?!

It’s no secret that I really despise the American education system and I was always disgruntled about being forced to attend college to get a degree simply to be taken seriously (i.e. getting a job with benefits). Knowing that, I shocked myself when I started thinking about going for a Master’s degree. As a campus employee, I am able to take classes and get a master’s degree at a heavily discounted rate. So the option was always available to me but I refused to pursue a master’s from the computer science department based on principal; their teaching ideals are heavily dated and obsolete, in my opinion. So I considered what other fields I could get a master's in and I started thinking about my minor during undergrad: GIS. Funny enough, as I was thinking about getting a master’s in GIS, I started consistently running into my one of my favorite professors on campus, Dr. Soheil Boroushaki. We grabbed lunch together and we discussed the GIS master’s program. After our lunch together, he had me sold on the program. But of course, I couldn’t tell him that immediately. I needed to pretend to think about it and I needed to figure out how to get my job to pay for my degree…

One of the things I hate the most is people complaining about a problem and doing nothing about it. Am I a hypocrite? I’ve been complaining about the education system for years and I have done nothing about it. Allow me to correct any misunderstandings. I am pursuing my master’s degree so that I may begin teaching at the college level and start doing my part, however small, in changing the education people receive. My current goal is to start teaching programming related GIS classes as soon as I get my degree.

The Rest

My high school has an event every year for its graduating seniors where alumni from the school will return for dinner and talk to seniors about their respective fields. Now, when I was a high school senior I was really interested in programming and signed up for the dinner with hopes of talking to a programmer. To my disappointment, I was paired up with an architect (I think) because there weren't any programmers available. Remember how I said I hated people who complain but don’t work towards change? Well this year, I reached out to my high school and told them that if they had any students interested in programming/technology, I’d be more than happy to come. Sure enough, they invited me to the dinner and I had a whopping two students interested! I was actually more surprised there were even two students who signed up with an interest in programming. I really hope I was able to give them some insight during our dinner. Also, I was one of the youngest alumni who was there. I was woefully under qualified to give them any life advice like the other alumni, but I at least knew my field! I hope to be able to continue being active in my high school's alumni community and participate in events like these in the future.

I’m a huge fan of Amanda Lee (aka AmaLee, aka Leeandlie) and her music and voice acting. I wasn’t able to find her original tweet but she mentioned a while back that someone was squatting on the domain she wanted: leeandlie.com; so she had to register leeandlieofficial.com. Well long story short, one day I was checking up on the domain out of boredom and found that it was able for me to acquire. And so I did. As soon as I had control of it, I redirected it to her (now) old domain and reached out to her to hand it over. Conclusion: she finally owns leeandlie.com.

I dragged my father to BABYMETAL’s first US arena show at The Forum and boy, was that an amazingly fun adventure; I’d definitely do it again and surprisingly enough, my dad would too.

I was invited to the GitHub Sponsors beta before it was released to the general public and I got my first two sponsors this year! I am really hoping that sponsoring open source developers becomes more common and that I may start working on projects that other individuals feel like sponsoring. Hint: I’ll gladly sell my soul for someone to sponsor me.

Software Accomplishments

What type of obsessive programmer would I be if I didn’t have a section dedicated to all my work in the open source community? Every year, there’s always something new and fun for me in the open source world and this year did not let me down. Here’s a summary of the most notable things that happened!

allejo/php-vcr-sanitizer reached 1.0.0 after learning that people were actually using it
scrivo/highlight.php had 14 releases this year; v9.13.1.1 through v9.17.1.0
The bzflag.org redesign was launched on April 1st after ~9 months of work; here's how we built it
stakx reached v0.2.0 after it was battle tested with the new BZFlag website
I joined the vfsStream team as a maintainer
Launched BZFlag Postgame and tagged 9 alpha versions for that project
Built allejo/bzflag-networking.php and released 9 versions of it
Refactored my personal website to use Bootstrap instead of Foundation
Open-sourced my VPNBlocker BZFlag plug-in and released v2.0.0
Contributed my first PR to OpenAPI Generator, fixing some TypeScript errors
Touched WordPress development again after years by contributing to Weston Router's Syntax Highlighting plugin
BZFlag Plug-in Starter hits version 3 with support for a lot of new options
bzfPluginGen was released and served as the core for v3 of my plug-in starter
Released @allejo/react-a11y-dialog as an NPM package forked from of Hugo Giraudel's project
jekyll-toc was adopted by more websites: City of Amsterdam, Intuit, Duality
jekyll-anchor-headings was adopted by awesome websites like: Bitrise, sitespeed.io, Duality, mlpack.org, Riot.js, "Just the Dogs" Jekyll theme, Microsoft’s TypeScript website, VMWare’s Octant documentation

What's next?

As I've mentioned before, I don't believe in whole concept of "new year new me" or doing something new in the new year. I'm content with where I'm at and I will continue to move forward with the same projects I've been working on.

The Unsolicited Job "Offer"

2019-07-19T08:00:00+00:00

When I was much younger, I'd get excited about receiving messages from recruiters on LinkedIn. I thought to myself that I was actually in demand. The ignorance of youth, am I right? Truthfully, I'm not popular enough or patient enough to get anything out of LinkedIn; so to me, it's mostly a joke and I treat it as such.

I accepted the job offer for my current position end of May 2018 and I updated my LinkedIn accordingly the same day so I wouldn't get recruiters sending me messages any more. Little did I know, that meant absolutely nothing to recruiters. I kept receiving unsolicited messages regularly from recruiters until mid August 2018 when I disabled InMails. Yes. I had to completely disable a feature on LinkedIn, because despite my happily starting a new job, apparently I was still wanted for "a great full-time opportunity with a profitable and long-standing successful company." That's right everyone, I got a job offer at—wait, what company is this that supposedly wants me? I was never told!

Did disabling InMails solve my problem? If you think so, you are horribly mistaken. Instead of InMails, I was now receiving connection requests from recruiters sending me their messages via friend requests. Why would anyone think that's a good idea?

Don't get me wrong, being a recruiter must be a tough job and I respect it. Every job is a respectable job. But please put effort into your job and don't just use the same generic and templated messages for everyone. One InMail I received included this gem:

We work using Paired Programming and Extreme Programming methods to build Next-Gen Tech from AI, Machine Learning to drones and we offer some amazing perks. No other company is doing what we are!

Every company is building "next generation technology" nowadays. If this were true, there would be a lot more real R&D going on for the betterment of society. Remember blockchain and the all hype it got? I'm sure that was "next-gen" too. Also, what is "extreme programming?"

Why am I giving recruiters such a hard time? Why am I hating on their methods? Because it's only fair to do so, in my opinion. As an employer, how would you feel if you got a resume that consisted of just the following:

Rock star programming
Worked on next-gen tech at a profitable and long-standing successful company
No other developer does what I do!

Would you call this individual in for an interview? I wouldn't. Not even if I was absolutely desperate, because it shows a lack of effort on the applicant's part. So when recruiters do essentially the same thing, it shows a lack of effort.

How do I solve this problem? Well, in my "about" section I have a little message hidden away. If you're truly interested in someone as a person, you should do them the courtesy of at least skimming their about section.

The way I see InMails is that it's all just a game. The way InMails work is that if the recipient responds to them within 90 days, the recruiter gets credit back for the InMail they sent you^[1]. As long as they receive some sort of response, even a rejection, they'll get their credit back; isn't that great? When I was receiving InMails the same week as I updated my new position, I simply stopped responding entirely to the InMails. If you're not going to do your due diligence of seeing that I had just started a new job, then you don't deserve your InMail back.

Fast-forward a year, I've reenabled InMail. I keep getting these ridiculous messages and connection requests. Wait. If I don't like LinkedIn, why do I still have one and advertise the link with my other social media links? Because it's blasphemy for someone in my age group not have one.

The Building of the New BZFlag.org

2019-04-13T08:00:00+00:00

For roughly 9 months, I had been working on the new website for the BZFlag project with the help of some awesome contributors; the planning and early work started in July 2018 but full speed development didn't really start until November 2018. On April 1st, 2019, the site was made live! I love a good and elaborate April Fools' joke, so what better way of participating this year than by launching a completely redesigned website for a project close to my heart? I mean, I also finally released my AOLer plug-in this year to troll but that's beside the point.

So what's the purpose of this blog post? Well, I wanted to write about everything I learned as I was building the new BZFlag site using my beloved stakx. This is a completely biased opinion but I must say, I built stakx to be pretty well balanced when it came to features.

The Good and Bad of CSS

As I was writing the page templates for the new site, I needed to decide on which CSS framework to use and how to use it. There are enough CSS frameworks out there as there are JS dependencies but the typical contenders are Bootstrap and Foundation. My site uses Foundation and I regret that decision, so I decided to use Bootstrap. Well, parts of Bootstrap that is. I used their grid system and some of their utility classes because I did not want their opinionated design nor was I going to use any of their components. I wanted full control of this design and I didn't want to bother reseting properties just to undo Bootstrap's UI.

Utility based CSS classes are great for prototyping and they saved me so much time by not forcing me to create unique classes for every single element. I want to add left and right padding for tablets and desktops? Cool! Let me just add px-md-3 to the element. But, what happens when I start having to create multiple copies of the same components or start having to add multiple rules or need custom rules?

Using Tailwind as an example, I'll build the same component with and without utility classes. Mind you, this is as close as I can get to the same components using Tailwind's default classes; once I need a more custom design, I have to do one of the following:

Add the styles via the inline style attribute
Create a custom Tailwind build, which means I now I have to bring in a node_modules folder with at least 80 dependencies and require all developers working on the site to have Node installed in addition to PHP.
Create my own custom classes; at which point, why the hell am I using Tailwind to begin with?

<a
  href="#"
  class="block relative overflow-hidden no-underline"
  style="box-shadow: 0px 2px 8px 1px #000; transition: box-shadow 0.2s;"
>
  <img
    class="absolute min-h-full min-w-full"
    style="left: 50%; top: 50%; transform: translate(-50%, -50%); transition: min-height 0.2s, min-width 0.2s; z-index:-1;"
    src="#"
    alt=""
  >
  <div
    class="flex flex-col p-4"
    style="background-color: rgba(0, 0, 0, 0.6); height: 300px; transition: background-color 0.2s;"
  >
    ...
  </div>
</a>

I'm aware of all the hype behind CSS Modules, CSS in JS, Styled Components, and hundreds more. Please. Fucking stop. There are times it's better just to do things "old school." Stop following the trends and think. Think about your project and requirements. Do you really need to bring in hundreds of dependencies just to build a website? The answer is a resounding no.

With the above example, I followed BEM with my CSS naming convention and all I'm using is good old Sass to generate whatever classes I need.

<a href="#" class="c-hover-card">
    <img class="c-hover-card__thumbnail" src="#" alt="">
    <div class="c-hover-card__body">...</div>
</a>

I have Sass variables and mixins to keep consistent values throughout my classes such as margin and padding. I have margin() and padding() mixins just so I can use them in the same way I would in HTML:

@include padding(x, 3);     // px-3
@include padding(y, 4, md); // py-md-4

Now, don't get me wrong. I have utility classes in my Sass but only the ones I need:

Borders
Display
Flexbox settings
Font sizes
Screenreader utilities
Spacing

I designed and built stakx to be the only executable you need to get a full-fledged static site built and I have accomplished just that. Despite some of the shortcomings of the PHP implementation of Sass, such as slowness and some bugs, it's a solid library and it's what stakx uses at its core.

Conclusion: There is absolutely no need to bring in Node as a dependency for the majority of cases. So, please. Stop doing so.

Collections + Searching

Just like a certain copyrighted animated individual, you want to collect them all! At its core, collections are one of stakx's most powerful feature. Some static site generators (SSGs) are designed for blogging, so collections for blog posts exist by default. Some SSGs have an opinion on where your collections should live and how they should be named. In stakx, there's no such thing. You create the collections you want, named whatever you want, wherever you want, and nothing more; the BZFlag site consists of 7 collections:

Generic Documentation
Flags
Slash Commands
Developer Documentation
API Events
API Functions
API Objects

Having collections in a site is no innovative concept to stakx, but what makes them so great? It's all Front Matter (YAML) + markdown; both are pretty standard across the Internet. That means any content within these collections could be parsed and reused anywhere else. Because all of our site's content is inside of collections, it was incredibly easy to build a search index by generating JavaScript with our Twig templates that would be read in by FlexSearch.js.

Let me just say. FlexSearch.js is amazing! It's stupidly fast and powerful. It's relatively new to the scene and for our purposes, it outshined lunr.js tremendously.

Due to problems we had with lunr.js not being consistent with searching, we had to explore alternatives. We even considered having a self-hosted search engine on a separate server. But. Why?! That means it's another service for us to maintain, theme, and host. If I haven't made it clear already, if there's no need to bring in unneeded dependencies, then why do so?

FlexSearch.js came to the rescue being the search engine we were looking for.

It's client-side, so nothing extra to maintain
It's stupid fast and efficient, so it's a reasonable burden on the browser
No dependencies! A single 6 KB minified file is all you need for the full feature set

Now, I know I've been going on about not having unneeded dependencies but a full-blown search engine with indexing, operators, partial matching, etc. is a necessary dependency. I don't have the time, patience, or knowledge to implement one myself.

So how did we get to building the search index source? We created a static PageView in stakx that will loop through all of our collections and build a JavaScript array of objects for FlexSearch.js to index.

---
title: Search Index
permalink: /search/index.js
---

const SearchIndex = [
    {% set uid = 0 %}
    {% for collection in site.collections %}
        {% for item in collections[collection.name] %}
            {
                id: {{ uid }},
                title: '{{ item.title }}',
                content: "{{ item.content | striptags | replace({'\n': ' '}) | escape('js') }}",
                permalink: '{{ url(item) }}'
            },
            {%- set uid = uid + 1 -%}
        {% endfor %}
    {% endfor %}
];

Remember old school web development when you needed to have multiple <script> tags and global variables? Yup! So long as you don't go to extremes, it's still an acceptable practice in my opinion.

<script src="{{ url(pages['Search Index']) }}"></script>
<script src="{{ url('/assets/js/flexsearch.min.js') }}"></script>
<script src="{{ url('/assets/js/search.js') }}"></script>

Finally, in our search.js, all we need to do is create the actual FlexSearch.js object and we're all set! We then wrote the rest of our vanilla JavaScript to read from an HTML <input> and call .search() when a form is submitted.

const idx = new FlexSearch({
    doc: {
        id: 'id',
        field: [
            'title',
            'content'
        ]
    }
});
idx.add(SearchIndex);

// ...
idx.search("your query", 10);

That's it! We have the majority of our site's content in appropriately nested folders, an entire client-side search engine, and only a single external dependency. Seriously, why the hell would you want to bring in Node.js, npm, Webpack, and all of those other hyped up tools when they're not actually needed? Please stop overcomplicating the Internet!

Conclusion: Save the bandwidth for Netflix binging.

Datasets

Datasets in stakx behave identically to collections with the exception that items in the datasets do not have bodies of content. The biggest benefit to having raw data is the fact that it can be reused anywhere else. On this site, we used a dataset to store release notes for all of our releases dating back to 1.7c, which was released on January 1st, 2000, in a parseable format. Moving forward, we essentially now have an authoritative change log in a maintainable and parseable format meaning we can build whatever we want with this data.

When it comes to stakx behavior, datasets behave similarly to collections meaning we can create a dynamic PageView and it'll render dedicated pages for each release from this data. And since all of the files in these datasets are parseable, if we need to manipulate the structure of the data, then we can write scripts to manipulate the data in memory and write back the changes to the files.

JavaScript-less Syntax Highlighting

Yup, you read that heading correctly. All of the syntax highlighting for the API docs on the site are handled entirely by stakx at compile time; that means no dependency on highlight.js or Prism.js. Want to load a page without JavaScript enabled? Sure! Go for it! Our code samples will still be highlighted for you.

This is all handled by the awesome highlight.php! A project I've adopted and now maintain. It's a loyal port of highlight.js written in PHP. This means two things:

all of the language definitions are being maintained by a mature and dedicated JS community; there's no need to rewrite or update language definitions separately
any stylesheet you find for highlight.js will work with highlight.php and therefore, stakx

PageViews

stakx's design philosophy is powered entirely by what are called PageViews. PageViews are essentially views in a traditional MVC pattern and stakx itself is the controller. However, these views are slightly more powerful than traditional views in which it can configure how the controller behaves.

Collection Management (Static + Dynamic PageViews)

There are three different types of PageViews: static, dynamic, and repeater. In the BZFlag site, we only made use of static and dynamic. How did we use these two types for managing collections and datasets?

_pages/../<collection>/
|- list.html.twig  # Static PageView
\- show.html.twig  # Dynamic PageView

Let's take the collection that contains Slash Commands docs as an example. The directory would be called slash-commands and there would be two files:

list.html.twig - A page to list all of the available slash commands organized how we wanted them, grouped by category in alphabetical order
show.html.twig - This is the dynamic PageView (or template, if you will) that will be used to display information for each slash command; e.g. parameters, description, version it was added, etc.

Static PageViews

Every other page that we need for the site worked out to be static PageViews. These are pages that just need markup and won't have its content or structure reused; e.g. the homepage. Sure the homepage will have reused components, but the page structure itself won't be reused for another page. Unlike collections, where the pages for slash command details all have the same sections.

Development Web Server

Now, I haven't explored how all the SSGs out there work, so this section is based on Jekyll's behavior. The way Jekyll works for a development server is it builds the entire site and then serves up those HTML files. I'm not sure how other SSGs handle this but stakx only parses the site's content and starts its web server. Nothing is built.

That's right. Absolutely nothing is built when you run stakx serve because why should it build the entire site? The way stakx works is it starts a web server that has an internal router. Then depending on the URL you go to, that's the single page it will build. Yup! If you go to localhost:8000/getting-started/ it will only build that page and its dependencies (e.g. CSS if Sass is used) and serve it to you. What if I change the base template of the theme that every page in the site uses? Will I have to wait for every single page to rebuild because I touched a core theme file? Don't be silly. How does that make sense? Oh wait. Jekyll does that. Yea… stakx only builds pages as you request them. That means I can change a core theme file and the next page load will probably be a few milliseconds slower because it's no longer cached but that's hardly noticeable.

Is it not fair that I'm hating on Jekyll alone? Ok, fine. Come hither, JavaScript based SSGs. Let me hate on you too. Alright, let's see. Why do I have to wait for the whole Webpack process to complete just for my development server to start? A Vuepress instance at my job takes 8 seconds to start. Seriously, how many dependencies do I need to wait to complete just to get a static site?

Conclusion

Why should you listen to me and what I wrote in this post? You shouldn't. After all, I graduated college less than a year ago and according to all the jobs who rejected me, I'm too young, don't know anything, and don't have the required amount of years of "full-time experience." Everything that I've learned on my own clearly means nothing, so please ignore everything you've read up until now.

On a less bitter note, here's something for you to wrap your head around:

the full BZFlag site is built by a single executable that's less than 2MB and that you can drag and drop anywhere
- the final BZFlag site consists of over 600 flat HTML files
the BZFlag website will load perfectly fine and will still work without JavaScript enabled in the browser (expect for the search)
there is a full client-side search engine that only relies on a single dependency and is built with vanilla JavaScript and the <template> tag
- no Vue, React, jQuery, Webpack, etc.
there is absolutely no use of Node or npm; with modern websites, this is blasphemy!

Please. Stop and think whether or not that framework or dependency is really necessary for your project. The Internet needs less overcomplicated things.

Now, in all seriousness, despite how simple or straightforward the BZFlag site seems to be built, there was a lot of thought that went into the structure and organization of it. Trust me, a lot of thought went into stakx's behavior too.

The Importance of a Community Manager

2019-01-27T08:00:00+00:00

A month ago, I went on a rant about showing your contributors some love and while I stand by that sentiment, I've learned something new in the past month: the importance of a community manager/advocate. Or just community engagement, in general.

What's happened in the past month that has led me to this new rant?

my PR to Docker to take down their GitHub hosted site (the one I submitted in April 2018) was finally merged in 🎉
I submitted PRs #1109, #1111, and #1112 to the Kong Docs fixing issues they had reported and have received silence
Docker Docs #7464 was closed with no real information from the team

So my great experiences with submitting PRs to Docker Docs and Kong Docs were due to team members who were very engaging with the community. In my last post, I mentioned @coopr and how enjoyable it was to work him. Since my last PR, it seems like he's parted ways with Kong and has started on a new adventure. Best of luck, Cooper!

What's so important about having someone engaging with the community? It's someone whose main focus will be engaging with the community, not someone volunteering their own time. Ideally, it will alleviate the burden on your developers so they can focus on writing code instead of balancing that with community engagement. Since Cooper's departure, it's felt to me like the existing PRs in that repo have received little to no attention unless the PRs were submitted by core developers themselves.

Another aspect of engaging with the community is communication and some transparency. I bring up PR #7464 as an example for lack of transparency and communication. The tl;dr of that PR is that Docker is forcing you to create an account to download Docker, when it's not actually necessary to do so. Originally Docker had allowed users to download without an account but the docs team changed this with no discussion with the community and then closed the PR reverting this with the following message:

This generated a lively discussion for the docs team; thanks for that.

- L-Hudson

When members of the community seem pretty adamant about an issue, I feel there should be more of a discussion and explanation when the maintainers have reached a conclusion. Don't just close something and hope people will shut up about it.

It wasn't until I recently hopped on a community call organized by a vendor we use at work that it finally hit me, whoever is leading the community engagement is really important. That call was actually enjoyable and I was taking the work of their community manager to granted. The fact that I had enjoyable interactions with my PRs before were because of the people who took responsibility for PRs from start to finish.

Show Your OS Devs Some Love

2018-12-28T08:00:00+00:00

I've been lurking around the open source community for about a decade now. I say lurking because I feel like I lurk more than I actually contribute. Though, judging by the little squares on my GitHub profile, I am by definition: fairly active. My favorite time of the year is Hacktoberfest because I do my best to find a community I don't typically hang around and see if I can contribute. Sure, I could always go to those "we'll accept any PR during Hacktoberfest" repositories, but where's the fun in that?

In the past, I really enjoyed making random appearances in the Docker Docs repository in unexpected ways.

I wrote an insane Liquid-only TOC generator for them that later became its own project that's now become my legacy...
I won second place in their 2017 Docker Docs Hackathon by contributing a complete rewrite of the site sidebars
- This PR alone fixed four issues: #2002, #2232, #2403, and #2692
- Additionally, it also fixed not one, not two, but three additional findings that didn't have respective issues yet

So if you're browsing the Docker Docs site and enjoy how smoothly the sidebars work with scrolling, how that hamburger actually appears at a reasonable breakpoint, or if you're maintaining the source and you like how the navigation for the entire site is now in a single include... You're welcome.

I loved the Docker Docs team at the time. I wasn't in any way affiliated with Docker, but they'd reach out to me from time to time with questions. I loved it. I was in college, so I needed something to keep me busy during my mundane classes and they gave me just that. Heck, they even sent me some free swag; thanks Misty!

As with anything in life, things change. My favorite docs team members left to other companies; good for them! I figured I'd continue to make appearances regardless so back in April 2018, I submitted a PR to take down the GitHub pages hosted version of the site; something they'd been asking for help with. At the time of writing this, the PR remains open and mostly untouched.

For Hacktoberfest, I looked through the PRs to see if the one I had created in April had finally been merged or closed. Maybe I missed the notification? Nope. Untouched since April. A few days later, it was bumped on the 4th. I thought to myself, "Ok, I guess taking down the GH version of the site might take some long internal discussion." I work for the government, I'm used to slowness in decision making. In the spirit of Hacktoberfest, I decided I'd try fixing some site bugs. I submitted PR #7496, which would fix the browser history spam you'd get as you scrolled through any page. Fast forward 2 months. Untouched. No comments. No labels. No assignments.

<sarcasm>Man, I'm really feeling the love from the Docker Docs team...</sarcasm>

Since I make it a personal goal to contribute to new communities during Hacktoberfest, I found Kong Inc. who was looking for a way to automate creation of Table of Contents on their GitHub pages hosted site. Doesn't that sound familiar to another community I once helped out? I submitted PR #920 and I had such an enjoyable experience in doing so! Working with @coopr was so productive! I had questions on how they wanted something implemented, they had answers and feedback quickly! It took about 13 days to iron out this PR and get things "just right" but it was well worth it. Not only did Kong get a new feature on their documentation site, it was discovered that there were many improvements and updates needed throughout. These were tackled by other members of the community in the coming days. Now that's what I call collaboration.

A few days later after my PR was merged, I get pinged on Twitter by the Kong account thanking me for adding the auto-TOC feature to their site. Then much much later, I get pinged once again telling me about how they mentioned me in their blog post. Kong gave me more attention than my parents ever did; it's such a nice feeling to be loved.

Huge thank you to @allejome, who added automatic table-of-contents generation to our documentation as part of #Hacktoberfest! Contributors like you are the stars of #OpenSource! Wondering what to work on to earn a contributor t-shirt?👕🎃🦍https://t.co/Rt1JBSl7kP
— Kong (@thekonginc) October 20, 2018

Really feeling the love, @thekonginc 🥰 thanks for the mention in this! https://t.co/hoVNFuTZI9
— Vladimir Jimenez 🇨🇦🧐 (@allejome) December 6, 2018

So what's the moral of this story?

Thank your open source contributors! A simple "thank you" when your merge their PR goes a long way. Tag them in release notes. Give them credit!
Be responsive and kind to PRs. Remember, people are taking time out of their day to contribute to your project. So be responsive and give them feedback. A PR will likely not be mergeable on the first try, so give them feedback on what to do to make it mergeable. There's nothing more satisfying to me than getting feedback from a team of a project I care enough about to contribute to.

It's really that simple. In this story, Kong Inc. went above and beyond with showing me so much love in everything they mentioned me in and I appreciate all of that! I'm really feeling the love from Kong. There's not a doubt in my mind that I'd return to the Kong community far quicker and more willingly than I would the Docker one.

Why I Built stakx

2018-09-01T08:00:00+00:00

I've been wanting to write something on my blog because I haven't written anything since May and for me, that's a long time. So I decided I'd write about why I decided to create stakx.

Arrogance: I was/am arrogant enough to believe that I could do a better job with features and design choices for how a site should be built
Challenge: I wanted to see how difficult it would be to create my own
Learning: I simply wanted to learn
Burger King: I wanted to have things my way

Static Site Generator (SSG) Comparisions

Any other sane developer would ask, "why don't you just use an existing SSG?" My answer to that is: I have used other SSGs and I found that they all fell short for my needs and wants.

Jekyll
- The Liquid template engine leaves a lot to be desired when compared to an engine like Twig
- You shouldn't be using Jekyll globally and instead need to install Bundler
- You're not supposed to modify your system installation of Ruby so you can't install Bundler without first configuring and using rbenv
Literally any JavaScript based SSG
- Please. No. Make it stop! As diverse as the JavaScript community may be, boy is it a dependency hell. Setting up a very simple website requires one or more of the following:
  - Install a binary "globally" with its own node_modules
  - Install it via package.json and with it, an unreasoably large node_modules folder per site
  - Some type of bundler/builder/task runner (Webpack, Grunt, Gulp, and friends)
Sculpin
- A step in the right direction, uses a powerful template engine
- Practically a PHP based version of Jekyll but with Composer needed instead of Bundler
Hugo
- Hugo got things right. Single binary that you can drop anywhere and run it.
- Their template engine? Could be improved.

Looking Back

There are a number of things I would design differently, a lot of which I've been able to rectify in stakx 0.2.0 development. There are a number of things that I'd have a hard time changing now, so I'm stuck with them. But looking back, would I still build my own SSG if I was given the chance?

Definitely.

stakx has been one of my largest open source projects that I've worked on my own that hasn't been related to an existing community. It's been a fun experience thus far creating something like this mainly for myself.

Is stakx for the masses?

Despite my most ambitious and obscure projects that all scream "what the hell are you doing?!" getting a lot of unexpected attention...

No. Not at all. stakx isn't meant for the masses.

While I'm designing stakx with backwards compatability in mind during breaking releases, I no longer have any dreams of stakx becoming a new hyped up SSG competitor. I'd honestly be more disappointed that my project got taken away from me by a community. It's fun making decisions without thinking of how it'd affect a lot of other people.

Jekyll Heading Anchors without JavaScript

2018-05-29T08:00:00+00:00

Despite all my efforts for developing the next major version of stakx, I come bearing gifts for the Jekyll community. When building websites with long pages, it has become the standard to include a table of contents that link to headings. Up until jekyll-toc, the only way to achieve that was through a Jekyll plugin or JavaScript. Now, the current solution for adding clickable links next to headings is to use JavaScript. Let's change that.

There are too many static websites out there that load a lot of JavaScript to the point where it slows down. Why? Seriously. Stahp that. I mean, I'm even planning on moving away from Disqus solely because it loads too much. Anyhow, websites like these cause me to navigate it with JavaScript disabled but that often leads to me not being able to click on a permalink for a heading. Taking the same behavior and concept from jekyll-toc, I've built jekyll-anchor-headings.

If things can be achieved without resorting to JavaScript, why not do it?

TL;DR

The code is available on GitHub: allejo/jekyll-anchor-headings.

Usage

Usage is simple, instead of using {{ content }} to display your page's content (your rendered markdown, i.e.) you would feed {{ content }} into the anchor_headings.html include.

{% include anchor_headings.html html=content %}

The snippet is available in the GitHub repo and has unit tests as well. We have to be sure that things continue working as expected with variations of HTML.

How it Works

Since jekyll-toc has worked out pretty robustly, I've taken a lot of the same concepts and code from that project and adapted it to work with this new project.

Step 0

Taking steps 1 through 6 from the previous post, we currently have access to the id attribute and the contents of the actual headings (e.g. h1).

Step 1

First, we build an anchor tag manually as a string by setting the href attribute along with class and title. So at this point, we'll have the following:

href="#some-id" class="my-class permalink" title="click me!"

Step 2

Now, we'll take that string and simple prefix <a and append an ></a> with possibly some content in between the anchors.

Step 3

We do some stupid string replacements to change the current heading tags (h1 - h6) with some that we build on our own with:

The custom anchor we built in steps 1 and 2
The heading content we have from step 0

Conclusion

Check out the project on GitHub and give it a shot on your own website! There's no need for you to understand the craziness of manipulating HTML as strings, just {% include %} in your layouts and you're set!

One Year of jekyll-toc

2018-04-21T08:00:00+00:00

Over a year ago, I wrote a table of contents generator for Jekyll websites, on a whim, using nothing but Liquid. There was a need for being able to generate table of contents for pages from a layout without relying on a plugin or JavaScript and without having to include {:toc} in every single markdown file. I never had a need for this feature, it was one of Docker's employees who was asking if a solution existed. I was intrigued by the problem and so I wrote my solution on a whim as a proof of concept; I really just wanted to know if I could achieve the same thing by using just Liquid.

It took me a few tries to actually figure out a robust solution to the problem but I succeeded; it got Docker's docs team's seal of approval. 🎉 I felt proud that I had done a thing! So I wrote up a blog post to feel important and that was the end of it. Or so I thought. A few months later, a developer from the UK Ministry of Justice showed up on IRC asking about this same problem. I linked him to my blog post and that's how I got my name in the UK Ministry of Justice's License file. Pretty damn awesome, am I right?

I got curious and looked into my site's analytics and did some Googling to see how common this problem was. Turns out, there were enough people having this problem to motivate me to move the snippet I wrote into its own GitHub repository. Heck, I even added unit tests to the repository and connected Travis CI with notifications to ensure that if I made changes to the Liquid snippet, that it'd still work.

I wanted to make sure that my effort of moving this into a repository wasn't wasted, so I did some searching on GitHub to see if I could shamelessly advertise my project; I found issue #1222 on the minimal-mistakes repository. Minimal Mistakes is one of the more popular Jekyll themes out there and I was able to get my project incorporated into that theme. How cool is that?! Thanks Michael Rose (@mmistakes)!

I was satisfied with this venture. It sated my desire for spreading my project. A few months passed and I had started getting a steady amount of traffic to my GitHub repository from my blog post and Google. I even got some feature requests and bug reports! Heck, even Bootstrap want(ed/s) to use it! (There have been a number of separate attempts for using this snippet on the official Bootstrap website but none of them have been merged, yet.)

Fast forward to now. I get @mentioned in issues/PRs every so often giving me credit for jekyll-toc and that's freaking awesome! Don't stop! I enjoy seeing where you're all using my project. Besides getting mentioned, I search GitHub on occasion to see how far my snippet has gone and I'm never disappointed. Just last month, I discovered that Apache is using it in some of their Jekyll sites. And just a few days ago, I discovered that JetBrains is using it in their new Jekyll theme! JetBrains has always had a special place in my heart because of their awesome IDEs and now, they're using something of mine! If only you could see my inner Jonah Hill fangirl squeeing right now.

Besides my code seeing the light of day in the United Kingdom, it has even made it to Japan as well! This is honestly a lot of fun for me and I'm really proud; the repository doesn't have hundreds of stars, nor does it need to have that many. I'm flattered by the reach this project has gotten. Thank you to everyone who has used or shared my little jekyll-toc project! Don't stop @mentioning me in your issues, PRs, or commit messages! Like I said, I love to see where jekyll-toc goes next!

BZFlag Plug-ins for Dummies: Chapter 9

2018-03-02T08:00:00+00:00

Happy new year! ...in March. It's a new year and I come bearing gifts as your resident BZFlag Santa Claus from beautiful Southern California: the place with a Starbucks in every corner and misspelled names on coffee cups in every trashcan. I'm here to bring you a surprise new chapter for BZFlag Plug-ins for Dummies covering world weapons, custom flags, and the latest improvements to the world weapon API.

What are world weapons? They are shots that are fired by the server instead of by tanks. Technically, the world and server are separate so they should be called "server shots" because it's actually the server shooting them but... They were dubbed world weapons so the name stuck. If you've played on Urban Jungle, Clay Hills, or Planet MoFo's Apocalypse, you've seen world weapons. They are those shock waves that happen when you drive over a mine and they are all those extra shots that exist on MoFo with flags like "Death Barrel" or "Triple Barrel."

The world weapon API has always been wonky, counterintuitive to use, not easy to work with, and synonyms. Whenever a tank or the server fires a shot, it is assigned two IDs: a local ID and a global ID. Since this series focuses on plug-in development and not BZFlag's protocol, we only care about a shot's GUID. Up until recent changes, the only way to know a shot's GUID was to assign it yourself, which doesn't sound too hard. It's not. The problem arises when you have multiple plug-ins shooting world weapons and they're each setting their own GUIDs; there are bound to be conflicts. Planet MoFo has run into this issue several times in the past and we've had to be meticulous about picking these shot GUIDs. The new functions that were introduced in the API for BZFlag 2.4.14 solves this issue by reworking how world weapons are handled and making use of GUIDs exclusively. The only API function you should be using to fire world weapons is bz_fireServerShot(); the other bz_fireWorldWep() and bz_fireWorldGM() functions are now deprecated and will be removed in the next major release.

I think that's enough of an explanation, so let's build a plug-in instead!

Plug-in Specification

In this chapter, we'll be building a plug-in that introduces a custom flag. When a player carrying this flag shoots another tank, the victim will die and a shockwave will explode at their location. If that shockwave hits any other enemy tanks, then those kills be credited to the original flag carrier. Let's call this flag, "Cascade."

Registering Custom Flags

Planet MoFo is known for its custom flags, so let's first explain how we create those custom flags. The BZFS API has a bz_RegisterCustomFlag() function, which is used for defining our flag's definition. Once the flag is defined and the plug-in is loaded, map makers and server owners can simply use +f to add those flags to a map.

bz_RegisterCustomFlag(const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality)

Let's create our own Cascade flag and of course, this will go in our plug-in's Init() method.

void CascadeFlag::Init (const char* config)
{
    bz_RegisterCustomFlag("CA", "Cascade", "All of your victims will trigger a shockwave at their death location", 0, eGoodFlag);
}

Now that we've registered our custom flag, let's figure out what this actually means.

abbr is the abbreviation of the flag name; i.e. one or two letter abbreviation of the flag name. Try to be unique and don't cause conflicts with existing flags
name is the full name of the flag
helpString is the message that appears under your mouse box in your HUD, which explains what the flag does
shotType is an enum but it was never implemented in the API, so just use 0
quality is whether the flag is an eGoodFlag or an eBadFlag

At this point, our brand new Cascade flag can be added to maps! However, it's as useful as the Useless flag. We will now need to implement the behavior we want. Going back to our specification, we want something to happen if someone shoots a tank with the flag and then shoot a shockwave at their location of death. If you guessed that we're going to listen to the player death event, you're right!

Implementing Custom Flags' Behavior

It's important that you implement custom flag behavior however you want, this example requires that we perform an action on a player's death. The first step is to register the player death event to notify BZFS that we want to listen to this event.

void CascadeFlag::Init (const char* config)
{
    Register(bz_ePlayerDieEvent);

    bz_RegisterCustomFlag("CA", "Cascade", "All of your victims will trigger a shockwave at their death location", 0, eGoodFlag);
}

Now, we need to implement what's going to happen when a player actually dies. Our goal is shoot a shockwave only when the Cascade flag is used, meaning we have to be explicit about it in our implementation.

void CascadeFlag::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_ePlayerDieEvent:
        {
            bz_PlayerDieEventData_V1 *data = (bz_PlayerDieEventData_V1*)eventData;

            if (data->flagKilledWith == "CA") // Step 1
            {
                // Step 2
                float vector[3] = {0, 0, 0};
                bz_fireServerShot("SW", data->state.pos, vector, data->killerTeam);
            }
        }
        break;

        default: break;
    }
}

Step 1

Make sure we only fire a world weapon shockwave when a player was actually killed with the Cascade flag. data->flagKilledWith will hold the abbreviation of the flag used to kill the player, so we compare it against our own abbreviation: CA.

Step 2

We have to create a vector for the direction our shot needs to take. However, because we're using a shockwave, there's no need to calculate the vector so we can set it to 0, 0, 0. However, this vector is calculated with the lookAt function. There are far more qualified people on Google to cover the maths behind this subject, so I'll let them do that. Thanks to JeffM for helping with all the maths used internally in BZFS for calculating world weapon directions.

uint32_t bz_fireServerShot(const char* shotType, float origin[3], float vector[3], bz_eTeamType color = eRogueTeam, int targetPlayerId = -1);

Destroyed by Server

Awesome! We're done, right? Build the plug-in and try it out. Let's look at the specification once again, did we get everything? The cascading affect of the flag doesn't quite work correctly... It shows that the those tanks in the shockwave radius were "destroyed by server." Why?

As I mentioned earlier, these shots are in fact fired by the server, so the death message actually makes sense. Can we make the owner of the server shot a player instead? It's called a server shot for a reason, so no, it's not possible. If only there were a way to reassign the killer in the death event...

World Weapon Management

Server shots will always be owned by the server and should remain as such. However, manipulating death data is something supported by the API so let's take advantage of that fact.

The bz_fireServerShot() function will return the GUID of the shot as a uint32_t so we should definitely store it because we'll be using it. Shots in BZFS are just objects stored in a fancy array and these objects support storing arbitrary information for each individual shot. Let's take advantage of this as well!

void CascadeFlag::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_ePlayerDieEvent:
        {
            bz_PlayerDieEventData_V1 *data = (bz_PlayerDieEventData_V1*)eventData;

            if (data->flagKilledWith == "CA")
            {
                float vector[3] = {0, 0, 0};
                uint32_t shotGUID = bz_fireServerShot("SW", data->state.pos, vector, data->killerTeam);

                // Step 3
                bz_setShotMetaData(shotGUID, "type", data->flagKilledWith.c_str());
                bz_setShotMetaData(shotGUID, "owner", data->killerID);

                return;
            }

            // Step 4
            uint32_t shotGUID = bz_getShotGUID(data->killerID, data->shotID);

            // Step 5
            if (bz_shotHasMetaData(shotGUID, "type") && bz_shotHasMetaData(shotGUID, "owner"))
            {
                // Step 6
                std::string flagType = bz_getShotMetaDataS(shotGUID, "type"); // 's' for string

                if (flagType == "CA")
                {
                    // Step 7
                    data->killerID = bz_getShotMetaDataI(shotGUID, "owner"); // 'i' for integer
                }
            }
        }
        break;

        default: break;
    }
}

Step 3

Let's make use of the fact that shots can store arbitrary information. Let's store two pieces of information: the "owner" of the shot (the player carrying the Cascade flag) and the "type" of flag. By storing these two pieces of information, we'll be able to know who to credit for the kill and avoid any conflicts with multiple world weapon shots from different flag types.

Step 4

Remember how I mentioned local IDs and global IDs at the beginning? Well, we have to use the local IDs to get the GUID. Let's just leave it at that because the GUID is all we really care about.

Step 5

Every shot on a server has a GUID and is a shot object in a fancy array; this means that we need to make sure the shot fired is a world weapon that we triggered and control. We confirm that the "type" and "owner" metadata exists for the shot. By doing so, we know that this shot has the structure that this plug-in uses and we're not interfering other shots.

Step 6

We now confirm that the shot is actually a Cascade shot by getting the "type" metadata. If another plug-in uses the "name" and "type" combination or this plug-in has multiple special flags, we'll know which shots we should actually work with.

Step 7

We reassign data->killerID to the "owner" of the world weapon so that they may take credit for the kill instead of the server.

Final Plug-in

That's it! The plug-in is now ready for action on your new map!

#include "bzfsAPI.h"

class CascadeFlag : public bz_Plugin
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);
};

BZ_PLUGIN(CascadeFlag)

const char* CascadeFlag::Name ()
{
    return "CascadeFlag";
}

void CascadeFlag::Init (const char* config)
{
    Register(bz_ePlayerDieEvent);

    bz_RegisterCustomFlag("CA", "Cascade", "All of your victims will trigger a shockwave at their death location", 0, eGoodFlag);
}

void CascadeFlag::Cleanup ()
{
    Flush();
}

void CascadeFlag::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_ePlayerDieEvent:
        {
            bz_PlayerDieEventData_V1 *data = (bz_PlayerDieEventData_V1*)eventData;

            if (data->flagKilledWith == "CA")
            {
                float vector[3] = {0, 0, 0};
                uint32_t shotGUID = bz_fireServerShot("SW", data->state.pos, vector, data->killerTeam);

                bz_setShotMetaData(shotGUID, "type", data->flagKilledWith.c_str());
                bz_setShotMetaData(shotGUID, "owner", data->killerID);

                return;
            }

            uint32_t shotGUID = bz_getShotGUID(data->killerID, data->shotID);

            if (bz_shotHasMetaData(shotGUID, "type") && bz_shotHasMetaData(shotGUID, "owner"))
            {
                std::string flagType = bz_getShotMetaDataS(shotGUID, "type");

                if (flagType == "CA")
                {
                    data->killerID = bz_getShotMetaDataI(shotGUID, "owner");
                }
            }
        }
        break;

        default: break;
    }
}

Conclusion

Awesome job! You've just completed your first plug-in that makes use of world weapons, custom flags, AND the new API that was just implemented this last weekend. World weapons aren't always easy to work with and can get pretty complicated so I'd highly recommend that you play around with this on your own.

This new chapter was solely inspired by the latest API changes that I've been working on with JeffM meaning this series is still on a hiatus. Once I am able to better explain the maths behind these calculations, I'll write another chapter dedicated to just that but until then, thanks for reading!

Recap of 2017

2017-12-13T08:00:00+00:00

It's been a busy semester, I just completed my second to last semester of my college career. The end of 2017 is approaching and what I have accomplished in the past year? Looking back, I don't really feel like I accomplished anything significant but here are some highlights.

BZiON reached version 0.10.0
stakx reached version 0.1.2 and development for the next major release has started
Became a contributor to highlight.php
Came second in the Docker Docs Hackathon by improving their navigation significantly
My jekyll-toc project has gotten some recognition
- The UK Ministry of Justice is using it
- It's included in the Minimal Mistakes Jekyll theme
- It was almost included in the Bootstrap website, however certain limitations prevented that from happening
Wrote 8 chapters about writing plug-ins for BZFlag

There are a number of projects that I'm currently working on that I haven't open sourced yet because I'm not content with the current state they're in; these are new projects that I'm still experimenting with. I do all of my open source work so I can learn and practice; I also do it because I genuinely enjoy it. Because I do it for fun, I don't expect or want anything in return but I don't want to be demoralized either. Without going off on a tangent or whining, here's a friendly reminder to show some appreciation to developers however you deem fit. It can be as simple as star'ing the repository on GitHub or a shout-out on Twitter or whatever platform. This has been the first year where I've gotten random mentions and recognition for some of my projects outside my typical circles and it's awesome! It's very encouraging and motivating to get that type of feedback.

What do I have planned for 2018? Well... The whole concept of doing something new in the new year seems rather ridiculous to me; I have goals and plans year around that rollover from year to year. I have at least 4 different projects that will overlap during my winter break from school. Is it crazy or unhealthy? Probably.

Breaking Columnar Transposition and Caesar Cipher

2017-10-13T08:00:00+00:00

It only took until I reached my final year in college to finally find a class I found challenging and actually learned from (excluding GIS classes). I've always been fascinated by cryptography and have always wanted to learn but never found the time to do so on my own. Until I took this class, I had no knowledge of how crytography actually worked. I found this assignment to be incredibly fun because it was challenging for me.

Heads Up

When I was first given this assignment, I searched the internet to see if anyone had already solved this. That's how code works, right? (I'm looking at you, left-pad). Unfortunately, I wasn't able to find anything. I say "unfortunately" but looking back at this, I'm really glad I didn't find anything or else I wouldn't have been able to challenge myself to figure this out.

There were several in my class that couldn't solve this assignment so I'll be posting this for future readers. However, I highly recommend that if you find cryptography interesting, to skim through this post at most. It's more fun to do it on your own, trust me.

Let's Get Started

I was given a cipher and was tasked with finding the keyword used to encrypt the plain text, and in turn, find the plain text. The plain text was encrypted using columnar transposition and a simple shift substitution.

HUKUUEUUYREUYYKGRRGNZZKXNGNOLKXTSAQNZYEGNZTRGTOYALSSEHSYGRVSOOLEGIKVKNZOEJYXT

All of this code is reliant on the pycipher project and uses Python 2, however it can easily be upgraded to Python 3.

Breaking the Simple Shift Substitution

To find the shift used for this half, the approach I used was to use frequency analysis on the original cipher. Certain letters are used far more than others in any language, so we'll take advantage of that by finding the most suitable value. An example of this would be that the letter Q is used far less in English than the letter A.

The frequency of letters in the English language can be found on the Internet, so these are the values that I used for this analysis. The following code is based on ActiveState's recipe for deciphering a caesar cipher.

ENGLISH = (0.0749, 0.0129, 0.0354, 0.0362, 0.1400, 0.0218, 0.0174, 0.0422,
           0.0665, 0.0027, 0.0047, 0.0357, 0.0339, 0.0674, 0.0737, 0.0243,
           0.0026, 0.0614, 0.0695, 0.0985, 0.0300, 0.0116, 0.0169, 0.0028,
           0.0164, 0.0004)

Now, we need to see how often each letter appears in our cipher text. To calculate the frequency of these letters we have a function called letter_frequency().

def letter_frequency(text):
    # For ease, remove all non-letter characters and convert it to lowercase for consistency.
    text = re.sub('[^a-z]', '', text.lower())

    # A dictionary to keep count of how many times each letter is used inside of `text`. They key will be the letter
    # being counted.
    alphabetCount = dict([(c,0) for c in string.lowercase])

    # Cast to float
    totalLetters = len(text) * 1.0

    for char in text:
        alphabetCount[char] += 1

    # Convert the dictionary to a list of items and sort them by the letter
    textLetterCount = alphabetCount.items()
    textLetterCount.sort()

    # Calculate the amount of times the letter has appeared in relation to the cipher's length
    return [ count/totalLetters for (letter,count) in textLetterCount ]

Now that we can calculate the frequency of letters in the cipher, we need to start calculating the deltas of each possible shift value (1 through 25). To first calculate the delta, we need a function that will calculate the difference between the frequency values we got from letter_frequency() and the hard coded values defined in the ENGLISH list.

def frequency_delta(source, dest):
    N = 0.0

    for f1, f2 in zip(source, dest):
        N += abs(f1 - f2)

    return N

The value we get from this function will be the total change in frequencies from our potential shift and the English language letter frequencies. The lower the frequency, the better the chances of that shift being our offset value. Now, finally, we just need to loop through all 25 possible shifts and find the one with the lowest frequency.

def decipher_caesar(cipher):
    lowestDelta = 1000 # A ridiculously large initial delta in order to ensure a new lowest delta
    bestRotation = 0
    letterFrequencies = letter_frequency(cipher)

    for shift in range(26):
        currentDelta = frequency_delta(letterFrequencies[shift:] + letterFrequencies[:shift], ENGLISH)

        if currentDelta < lowestDelta:
            lowestDelta = currentDelta
            bestRotation = shift

    return {
        'rotation': bestRotation,
        'plain_text': Caesar(bestRotation).decipher(cipher)
    }

After we run the decipher_caesar() function on our initial cipher, we get the following information:

Lowest delta frequency: 0.478501298701
Rotation: 6
Plain Text: BOEOOYOOSLYOSSEALLAHTTERHAHIFERNMUKHTSYAHTNLANISUFMMYBMSALPMIIFYACEPEHTIYDSRN

Breaking Columnar Transposition

Breaking this isn't quick and easy like the Caesar cipher but that doesn't mean it's difficult either; it's just very time consuming once you get the concept of it.

Columnar transposition makes use of a keyword to encrypt text; however, two different keywords could possibly encrypt the same plain text the same way. For example, using CAT and BAT as keywords would encrypt to the same result since they'd both order the columns as 213. We can use this fact to our advantage and just use numbers when trying to find possible keywords.

The length of the keyword is important and without knowing this information, it makes finding the keyword take far longer since we'll have to try out different lengths. To represent our keyword, I'll be using numbers. Since I'm writing this after I figured out the keyword, I know the length is 8 so we'll be using 8 numbers: 01234567 (because arrays start at 0).

The first step we need to do is create all of the possible permutations of our potential keyword, meaning we'd have a list looking like:

Don't worry, we'll build them all with itertools.permutations.

import itertools

permutations = itertools.permutations('01234567')

Now that we have every possible permutation, 40,320 to be exact, or 8!, we need to undo the columnar transposition of the cipher text with each permutation and save it.

from pycipher import ColTrans

def brute_columnar_transposition(text, keyword):
    possible_orders = permutations(keyword)
    columnPositions = {}

    for order in possible_orders:
        key = ''.join(order)
        columnPositions[key] = ColTrans(key).decipher(text)

    return columnPositions

With this function, we'll be getting every possible arrangement of the cipher's columns. But that's still 40,320 combinations. Unless you are really bored to do it manually, it's necessary to use a dictionary attack on all of these combinations and then find which version has the most English words.

I highly recommend you do not use your OS' dictionary if you're on Unix. Why?

allejo$ wc -l /usr/share/dict/words
235886 /usr/share/dict/words

What's worse is that these words are in alphabetical order, which will take forever to find a word such as "which" that is used frequently. To solve this issue, we need a shorter list of common English words (ideally sorted by frequency). Thankfully, someone on GitHub did just that and built a list containing the 10,000 most common English words in order of frequency.

# Build a list of English words from a file that's delimited by new lines
def build_dictionary():
    with open('10k-english.txt', 'r') as dict_file:
        return dict_file.read().split()

Now that we have a dictionary and all of the possible ordering of cipher columns, we'll perform the dictionary attack and we will write all of this information to a text file because it'll be a lot.

combinations = brute_columnar_transposition(
    'BOEOOYOOSLYOSSEALLAHTTERHAHIFERNMUKHTSYAHTNLANISUFMMYBMSALPMIIFYACEPEHTIYDSRN'
)

def dictionary_attack(permutations, words, output = 'iambrute.txt'):
    results = {}

    for cols, string in permutations.iteritems():
        results[string] = {
            'cols': cols,
            'words': []
        }

        for _word in words:
            word = _word.strip().upper()

            if len(word) < 3:
                continue

            if word in string:
                results[string]['words'].append(word)

    sortedResults = OrderedDict(sorted(
        results.iteritems(), 
        key=lambda x: len(x[1]['words']), 
        reverse=True
    ))

    with open(output, 'w') as data_file:
        for k in sortedResults:
            line = "{}: [{}]\n".format(
                ', '.join([ sortedResults[k]['cols'], k ]),
                ', '.join(sortedResults[k]['words'])
            )
            data_file.write(line)

    return results

During the process of finding English words, we are ignoring any words less than 3 letters long and making a list of words that exist in each of the combinations. Ideally, you'd want to ignore overlapping words so you don't find "THE" and "EAT" inside of "THEATER". However, it never hurts to find more words within already existing words; it'll increase its ranking.

Once we finish finding all of the words that exist in each of the combinations, we create an OrderedDict sorted by the amount of words that exist in the string in descending order so the string with the most words will be at the beginning of the file.

Results

I've made my code available on GitHub for you to explore and learn from. Since the code's public, it has likely been indexed by Google, meaning: if you found it, so can your professor. Don't get caught cheating.

Here's the plain text I got from my cipher.

Column Order: 03247615
Plain Text: BEHAPPYFORTHEMOMENTTHISMOMENTISYOURLIFEBYKHAYYAMOHANDALSOTHISCLASSISREALLYFUN:
Words Found: [THE, AND, FOR, THIS, YOU, YOUR, ALL, OUR, HIS, ALSO, THEM, LIFE, REAL, CLASS, MEN, REALLY, HAND, FUN, FEB, URL, HAPPY, LAS, MOMENT, FORT, MOM, FORTH, APP, ENT, MENT, HAY]

BZFlag Plug-ins for Dummies on Hiatus

2017-09-14T08:00:00+00:00

I never expected the BZFlag Plug-ins for Dummies series to get much traffic due to its nature; a very small community, few to no developers, etc. With regards to the current status of the project, I feel that I have covered enough of the API and plug-in writing to be helpful to new developers. For this reason, I'll be putting this series on hold for a while; by doing so, it'll allow me to focus on other projects that require my attention.

There is no estimate for how long this project will be on hold for. If you were following the series and would like to see it continued, please let me know and tell me what you'd like to see covered. Until next time, thanks for the support! ♥

BZFlag Plug-ins for Dummies: Chapter 8

2017-09-02T08:00:00+00:00

A common task to achieve in plug-ins is to have a countdown or time delayed functionality. As an example, a plug-in introducing a custom game mode such as Last Tank Standing will need a countdown for the last 5 seconds of each round and will need to kick a new player at a set interval. This is C++ so there's no magic setTimeout() function that we can use and there's no API function; instead we'll have to make use of the bz_eTickEvent and time_t objects.

The Tick Event

The bz_eTickEvent is an event that occurs every tick in the main BZFS loop. So, what's a "tick?" A single tick does not mean a single second; typically there are more ticks per second and it's never a consistent amount. Because ticks aren't designed to be used as an accurate measurement of time, we use a time_t object, which was designed to handle time.

Plug-in Specification

We'll be a building a plug-in that handles a timed game with a 5 second countdown after the /start slash command is executed.

The Setup

We'll be needing to create 3 separate variables to handle the 5 second countdown.

isCountdownInProgress - Whether or not a countdown is progress (optional, but very handy)
countdownTotal - The amount of seconds we will announce in our countdown
lastCountdownCheck - This time_t object will be used to keep the timestamp of the last time we announced a second in our countdown.

class TimerPlugin : public bz_Plugin
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);

    bool isCountdownInProgress;
    int countdownTotal;
    time_t lastCountdownCheck;
};

void TimerPlugin::Init (const char* config)
{
    isCountdownInProgress = false;
}

First, we'll be implementing our /start slash command, which will start our countdown. What we need to do is the following:

Set our boolean to true so we have easy access to check whether or not a countdown is progress
Set the amount of seconds our countdown will go on for
Set the timestamp of our last check to the current time

bool TimerPlugin::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "start")
    {
        isCountdownInProgress = true; // 1
        countdownTotal = 5;           // 2
        time(&lastCountdownCheck);    // 3
        return true;
    }

    return false;
}

Now, let's take a look at implementing the actual countdown which will happen in the tick event. So what's actually happening? Imagine a cliché family road trip where the children are asking, "are we there yet?" repeatedly. Our plug-in will behave exactly the same way, except it'll be asking: "has it been at least one second since my last announcement?"

It's very important to notice the "at least one second" in the question. As mentioned, ticks happen at uneven intervals so it's quite possible that the last tick happened 1.6 seconds ago. If we check if it was exactly 1 second ago (with ==), chances are we'll miss a tick and we'll never continue in the countdown because the difftime() value will never be exactly 1 again. By checking if it's been at least one second, we don't care if the last tick was 1.6 seconds ago, we'll still be able to continue.

case bz_eTickEvent:
{
    // We only want to care about checking timestamps if the countdown is in progress
    // ...remember we want to be efficient and quick in our plug-ins.
    if (isCountdownInProgress)
    {
        time_t currentTime;
        time(&currentTime);

        // difftime() returns the difference in time objects in seconds
        if (difftime(currentTime, lastCountdownCheck) >= 1)
        {
            bz_sendTextMessage(BZ_SERVER, BZ_ALLUSERS, "%d...", countdownProgress);

            time(&lastCountdownCheck); // Update the time of the last number announced
            countdownProgress--; // Decrease the amount of seconds we still have to go in our countdown
        }
    }
}
break;

Looks good, right? Yea. But we're not done. If you examine this example closer, you'll notice that we don't actually stop the countdown after it's been started; meaning we'll start announcing negative numbers and countdown indefinitely. Let's fix that.

Once our countdown progress reaches zero after all the countdownProgress-- decrements, we set our isCountdownInProgress boolean to false and we'll no longer enter this bit of code in the next tick event until another /start is executed.

case bz_eTickEvent:
{
    if (isCountdownInProgress)
    {
        time_t currentTime;
        time(&currentTime);

        if (difftime(currentTime, lastCountdownCheck) >= 1)
        {
            if (countdownProgress <= 0)
            {
                isCountdownInProgress = false;
                bz_sendTextMessage(BZ_SERVER, BZ_ALLUSERS, "The countdown is over. Good luck and have fun!");
            }
            else
            {
                bz_sendTextMessagef(BZ_SERVER, BZ_ALLUSERS, "%d...", countdownProgress);

                time(&lastCountdownCheck);
                countdownProgress--;
            }
        }
    }
}
break;

Our Complete Plug-in

#include "bzfsAPI.h"

class TimerPlugin : public bz_Plugin, public bz_CustomSlashCommandHandler
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);
    virtual bool SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params);

    bool isCountdownInProgress;
    int countdownTotal;
    time_t lastCountdownCheck;
};

BZ_PLUGIN(TimerPlugin)

const char* TimerPlugin::Name ()
{
    return "Timer Plugin";
}

void TimerPlugin::Init (const char* config)
{
    Register(bz_eTickEvent);

    bz_registerCustomSlashCommand("start", this);
}

void TimerPlugin::Cleanup ()
{
    Flush();

    bz_removeCustomSlashCommand("start");
}

void TimerPlugin::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_eTickEvent:
        {
            if (isCountdownInProgress)
            {
                time_t currentTime;
                time(&currentTime);

                if (difftime(currentTime, lastCountdownCheck) >= 1)
                {
                    if (countdownProgress <= 0)
                    {
                        isCountdownInProgress = false;
                        bz_sendTextMessage(BZ_SERVER, BZ_ALLUSERS, "The countdown is over. Good luck and have fun!");
                    }
                    else
                    {
                        bz_sendTextMessagef(BZ_SERVER, BZ_ALLUSERS, "%d...", countdownProgress);

                        time(&lastCountdownCheck);
                        countdownProgress--;
                    }
                }
            }
        }
        break;

        default: break;
    }
}

bool TimerPlugin::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "start")
    {
        isCountdownInProgress = true;
        countdownTotal = 5;
        time(&lastCountdownCheck);

        return true;
    }

    return false;
}

Conclusion

The BZFS API doesn't have a setTimeout() function nor does it have any custom countdown functionality, so we're left to implement things ourselves. My Last Tank Standing plug-in makes use of this technique for the countdown at the beginning of each match and also to keep track of the duration of each round to kick a new player.

BZFlag Plug-ins for Dummies: Chapter 7

2017-08-19T08:00:00+00:00

The next topic I'd like to cover regarding plug-in writing is how to create custom map objects. Have you ever played the King of the Hill (KOTH), All Hands on Deck (AHOD), or Jumping Skills? In this chapter we'll be building a plug-in that knows when players enter a specified zone to control the hill, capture the flag, or save at a check point. Prior to May 2015, you would have to write all of the logic and math yourself if you wanted to support custom zones. Thanks to the bz_CustomZoneObject class, courtesy of yours truly, all of the math and logic has been moved to the API and requires no effort on your part.

These custom map objects are not visible to players. Think of them as the same as a BZW zone object, which has no visible form.

Registering Your Map Object

The first step is to make your plugin extend the bz_CustomMapObjectHandler abstract class, which will require you to implement a virtual function.

virtual bool MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data);

This virtual function is called during the process of reading the map file and will give you access to every map object. Implementing this virtual function can also help you keep track of bases, teleporters, or any other map object you'd like. We'll be using this function to parse the information of our custom map object.

Similar to creating custom slash commands, you'll be making use of two functions in our Init() and Cleanup() methods, respectively. This is necessary, otherwise BZFS will not know that your custom map object is a valid object.

bz_registerCustomMapObject()
bz_removeCustomMapObject()

Here's what our setup will look like so far. Now if we load a map file with our custom map object, nothing will happen but an error won't be thrown either.

class FlagTakeZonePlugin : public bz_Plugin, public bz_CustomMapObjectHandler
{
public:
    // ...
    virtual bool MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data);
};

BZ_PLUGIN(FlagTakeZonePlugin)

void FlagTakeZonePlugin::Init (const char* /*commandLine*/)
{
    Register(bz_ePlayerUpdateEvent);
    bz_registerCustomMapObject("flagtakezone", this);
}

void FlagTakeZonePlugin::Cleanup (void)
{
    Flush();

    bz_removeCustomMapObject("flagtakezone");
}

Defining Your Map Object

After registering your custom map object, you're going to want to create your own class to handle any of the logic necessary. Thanks to the bz_CustomZoneObject class, we won't have to implement any logic for finding the position or rotation of our objects. We just have to implement our own custom logic, if any.

We'll be building a custom zone where certain flags are forbidden and if a player enters the zone carrying that flag, we'll take it from them. We'll also have an optional setting where this zone will only affect rogues. The class for our map object will have a vector of the forbidden flags and will look like so.

class FlagZone : public bz_CustomZoneObject
{
public:
    FlagZone() : bz_CustomZoneObject() {}

    bool rogueOnly;
    std::vector<std::string> forbiddenFlags;
};

Parsing Your Map Object (Part 1)

The next step in this plug-in is to actually parse the map object and save the details/configuration to our code. We do this in our implementation of the MapObject() method of our plug-in.

It's important that we only read the map objects that we want to be efficient. As I mentioned, this method will run for each map object in a map file, so we should be sure to quickly exit our MapObject() implementation if the current map object isn't one that we want or it has no data.

bool FlagTakeZonePlugin::MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data)
{
    // Note, this parameter will be in uppercase
    if (object != "FLAGTAKEZONE" || !data)
        return false;
}

For the rest of the method, we'll be handling the parsing and saving of the data. But we'll be needing a location to save our zones, so for that reason we'll be creating a vector in our class definition and saving our zones to that.

class FlagTakeZonePlugin : public bz_Plugin, public bz_CustomMapObjectHandler
{
public:
    // ...
    virtual bool MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data);

    std::vector<FlagZone> zones;
};

Now that we have a location to save our zone data to, let's start parsing and saving the data from the map objects. Given a custom map object that follows this specification:

flagtakezone
    position 0 0 0
    size 10 10 10
    take US
    take WG
    rogueonly
end

In this specification, the take key will take 1 value and that's the flag abbreviation. There will also be an optional rogueonly key that takes no parameters. This will be reflected on our MapObject() implementation.

Let's take this slowly, so let's go over the first steps in handling our zones.

bool FlagTakeZonePlugin::MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data)
{
    if (object != "FLAGTAKEZONE" || !data)
        return false;

    // Step 1
    FlagZone newZone;

    // Step 2
    newZone.handleDefaultOptions(data);

    // Step 3
    zones.push_back(newZone);

    return true;
}

Step 1

At this point, we know we're handling a "flagtakezone" so we'll have to create an instance of a FlagZone. This instance will be the zone object we use while reading this map object.

Step 2

Remember all of the math and logic I mentioned that you didn't have to take care of? Well, this is it. The handleDefaultOptions() function will automatically determine if the object is a box or a cylinder, calculate the position, sizing, and rotation. Later on, all we have to do is call the pointInZone() method and we'll know whether a given point is inside this zone or not. Awesome, right?

Step 3

After we've parsed the data for our object, let's add it to our vector so our plug-in can know this zone exists and so it can handle more than one.

Parsing Your Map Object (Part 2)

Now that we've take care of the "built-in" options for our map object, we'll need to take care of our custom options. In this step, we need to loop through the rest of the data in the map object, parse it, and save it. What data am I talking about? The custom take and rogueonly options that our map object supports. All of this information is stored in our data argument, which we must loop through.

The map object data stored is an array of the data in the object delimited by new lines. Basically, we have an array that looks like this:

["position 0 0 0", "size 10 10 10", "take US", "take WG", "rogueonly"]

We'll be using a for loop to go through each of these lines and save them to an std::string for convenience. By calling handleDefaultOptions(), we don't have to worry about position or size or any of those other "built-in" options. We just need to handle our own additional options.

bool FlagTakeZonePlugin::MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data)
{
    if (object != "FLAGTAKEZONE" || !data)
        return false;

    FlagZone newZone;
    newZone.handleDefaultOptions(data);

    // Loop through all of the data
    for (unsigned int i = 0; i < data->data.size(); i++)
    {
        std::string line = data->data.get(i).c_str();
    }

    zones.push_back(newZone);
    return true;
}

Now that we'll looping through our data, let's actually parse it and make sense of it. We'll make use of bz_APIStringList's awesome tokenizing functionality so we don't have to worry about building our own tokenizer or using Boost.

for (unsigned int i = 0; i < data->data.size(); i++)
{
    std::string line = data->data.get(i).c_str();

    // Step 4
    bz_APIStringList nubs;
    nubs.tokenize(line.c_str(), " ", 0, true);

    if (nubs.size() > 0)
    {
        // Step 5
        std::string key = bz_toupper(nubs.get(0).c_str());

        // Step 5.1
        if (key == "TAKE" && nubs.size() > 1)
        {
            newZone.forbiddenFlags.push_back(nubs.get(1).c_str());
        }
    }
    else
    {
        // Step 6
        std::string key = bz_toupper(line.c_str());

        // Step 6.1
        if (line == "ROGUEONLY")
        {
            newZone.rogueOnly = true;
        }
    }
}

Step 4

Following the BZW language definition, we'll be tokenizing on a single space between values.

You could do your own custom definition here if you'd like, but I highly recommend following the BZW convention and making it easy for map makers to stay consistent.

Step 5

If our tokenizer resulted in more than one value, that means we have a line with parameters. Because BZW is case-insensitive, I'll convert the first token to uppercase so we can compare it with our known options.

You may also convert it to lowercase instead, but I prefer using uppercase since that's how the object value is defined.

Step 5.1

Since we only have the take option that accepts parameters, our if statement is pretty simple. However, the more options you support, the longer your if statement may be.

Lastly, we'll take the second token, which we expect to be our flag abbreviation, and we'll push it into the vector of our FlagZone instance.

Step 6

Since we don't have any tokens, that means it's a line without any parameters. Convert it into uppercase for the same reason as before.

Step 6.1

Because we only have a single option that takes no parameters, we just need to check for the rogueonly option and set it accordingly in our FlagZone instance.

Making Use of Your Map Object

Now that we've defined our object, parsed it, and saved all of the data... Let's actually do something with it! We'll be hooking into bz_ePlayerUpdateEvent so we can listen to player updates, which happens a lot.

As mentioned earlier, all of our zones have a convenient pointInZone() method, which we will be using to check each player update to see if they're in a zone.

// Step 7
std::string currentFlag = bz_getPlayerFlag(updateData->playerID);

if (currentFlag.empty())
{
    return;
}

for (auto &zone : zones)
{
    // Step 8
    if (zone.rogueOnly && bz_getPlayerTeam(updateData->playerID) != eRogueTeam)
    {
        continue;
    }

    // Step 9
    if (zone.pointInZone(updateData->state.pos))
    {
        // Step 10
        for (auto flag : zone.forbiddenFlags)
        {
            if (currentFlag == flag)
            {
                bz_sendTextMessagef(BZ_SERVER, update->playerID, "This %s flag is forbidden here", currentFlag.c_str());
                bz_removePlayerFlag(update->playerID);
            }
        }
    }
}

Step 7

Get the current flag of the player and store it in an std::string for convenience. If the player doesn't have a flag, we don't have to bother checking through any of the zones.

Step 8

We need to be able to short circuit if the current zone we're checking is "rogue only" and the player isn't a rogue. Checking a boolean and a team is faster than calculating whether or not a player is in a zone.

Step 9

By using our handy pointInZone() method, we can check if the player is inside our zone.

Step 10

At this point, we've determined that our player is inside our zone, is carrying a flag, and we need to check whether the flag is forbidden or not. We loop through the forbidden flags defined for this zone and we remove the flag if it's a match.

Our Complete Plug-in

#include "bzfsAPI.h"

class FlagZone : public bz_CustomZoneObject
{
public:
    FlagZone() : bz_CustomZoneObject() {}

    bool rogueOnly;
    std::vector<std::string> forbiddenFlags;
};

class FlagTakeZonePlugin : public bz_Plugin, public bz_CustomMapObjectHandler
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);

    virtual bool MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data);
};

BZ_PLUGIN(FlagTakeZonePlugin)

const char* FlagTakeZonePlugin::Name ()
{
    return "Flag Take Zone Plugin";
}

void FlagTakeZonePlugin::Init (const char* /*commandLine*/)
{
    Register(bz_ePlayerUpdateEvent);

    bz_registerCustomMapObject("flagtakezone", this);
}

void FlagTakeZonePlugin::Cleanup (void)
{
    Flush();

    bz_removeCustomMapObject("flagtakezone");
}

bool FlagTakeZonePlugin::MapObject (bz_ApiString object, bz_CustomMapObjectInfo *data)
{
    if (object != "FLAGTAKEZONE" || !data)
        return false;

    FlagZone newZone;
    newZone.handleDefaultOptions(data);

    for (unsigned int i = 0; i < data->data.size(); i++)
    {
        std::string line = data->data.get(i).c_str();

        bz_APIStringList nubs;
        nubs.tokenize(line.c_str(), " ", 0, true);

        if (nubs.size() > 0)
        {
            std::string key = bz_toupper(nubs.get(0).c_str());

            if (key == "TAKE" && nubs.size() > 1)
            {
                newZone.forbiddenFlags.push_back(nubs.get(1).c_str());
            }
        }
        else
        {
            std::string key = bz_toupper(line.c_str());

            if (line == "ROGUEONLY")
            {
                newZone.rogueOnly = true;
            }
        }
    }

    zones.push_back(newZone);
    return true;
}

void FlagTakeZonePlugin::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_ePlayerUpdateEvent:
        {
            bz_PlayerUpdateEventData_V1 *updateData = (bz_PlayerUpdateEventData_V1*)eventData;

            std::string currentFlag = bz_getPlayerFlag(updateData->playerID);

            if (currentFlag.empty())
            {
                return;
            }

            for (auto &zone : zones)
            {
                if (zone.rogueOnly && bz_getPlayerTeam(updateData->playerID) != eRogueTeam)
                {
                    continue;
                }

                if (zone.pointInZone(updateData->state.pos))
                {
                    for (auto flag : zone.forbiddenFlags)
                    {
                        if (currentFlag == flag)
                        {
                            bz_sendTextMessagef(BZ_SERVER, update->playerID, "This %s flag is forbidden here", currentFlag.c_str());
                            bz_removePlayerFlag(update->playerID);
                        }
                    }
                }
            }
        }
        break;

        default: break;
    }
}

Conclusion

Congrats on building your first plug-in that adds a custom map object! Supporting custom map objects may seem pretty inefficient and resource intensive but so long as you write your code responsibly, no extra lag will be introduced due to these zones.

Epilogue

My apologies for this chapter being one week late! I had originally written it with less detail and decided to give myself another week to add more detail and rewrite parts of it. As an update, the release schedule for this series has changed to being every other Saturday. With school starting soon and topics requiring more detail, I won't be able to write them as quickly as I had originally intended. Thanks for understanding.

BZFlag Plug-ins for Dummies: Chapter 6

2017-07-29T08:00:00+00:00

In honor of my latest commit, of adding a new parameter to bz_addURLJob(), this chapter will be covering making URL requests and handling the return data. Why would a plug-in need to make URL calls? Well, a plug-in may need to communicate with an API but don't expect instant results, there'll be a small delay. A common plug-in that makes use of API calls would be my own League Overseer, which communicates with the league's API to report matches automatically. There are two different ways of doing URL jobs in a plug-in.

Create the URL job and forget about it, meaning you don't care about the results returned by the website you're calling
Create the URL job and execute code based on the returned data from the website

We'll be handling both situations in this chapter. If your plug-in will be working with the returned data, you will need to extend the abstract class, bz_URLHandler_V2. By extending this abstract class, you will have to implement 3 methods:

URLDone() - This method is called whenever a URL job is completed.
URLTimeout() - This method is called when a URL job times out.
URLError() - This method is called when a URL job results in an error.

class SAMPLE_PLUGIN : public bz_Plugin, public bz_URLHandler_V2
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);

    // Virtual methods from `bz_URLHandler_V2`
    virtual void URLDone (const char* URL, const void* data, unsigned int size, bool complete);
    virtual void URLTimeout (const char* URL, int errorCode);
    virtual void URLError (const char* URL, int errorCode, const char *errorString);
};

Making the URL Calls

When making URL calls, you'll be using the bz_addURLJob() function anywhere in your plug-in but don't expect instant results. Oh, and don't worry about pausing execution while waiting for a response, the game and code will go on¹. Here's the definition of the function we'll be using and its parameters:

bool bz_addURLJob(const char* URL, bz_URLHandler_V2* handler, void* token, const char* postData = NULL, bz_APIStringList *headers = NULL);

Name	Description
URL	The URL you'll be making the call to
handler	The class which implements the callbacks needed to handle returned data
token	A way to keep track of which job is which when running multiple
postData	An ampersand delimited and URL encoded list of data that will be used as POST data
headers	An array of HTTP headers that will be used in your URL call

Notes

This does not imply threads or asynchronous behavior. Your plug-in is still running in the main server loop so be efficient.

URL Calls without Callbacks

Let's consider a plug-in that will record player joins and send the data to a website to log players' online status, similar to Strayer's bzstats but this'd be real-time since it'd report player activity as it happens. We won't care about the data that was returned in this particular situation so we won't worry about specifying a handler, we'll leave it as NULL.

The first parameter of the function is a URL, this is the URL we'll be sending the data to. The second important bit is the data that we'll be sending as POST data, as we typically would: delimited by ampersands and URL encoded values.

argumentOne=hello%20world&argumentTwo=10

We will have to build the POST data ourselves and give it to our function to send in the URL job. We will be providing all of the formatting ourselves (ampersands and equal signs) and we need to make sure we encode all of our values so nothing breaks. To encode our values, bz_urlEncode() is provided but it expects a const char* so we'll be doing a lot of casting so we can continue to work with objects instead of pointers.

case bz_ePlayerJoinEvent:
{
    bz_PlayerJoinPartEventData_V1 *data = (bz_PlayerJoinPartEventData_V1*)eventData;

    std::string urlQuery;
    urlQuery += "callsign=" + std::string(bz_urlEncode(data->record->callsign.c_str()));
    urlQuery += "&bzID=" + std::string(bz_urlEncode(data->record->bzID.c_str()));

    // urlQuery -> "callsign=allejo%20bot&bzID=12345"

    bz_addURLJob("http://localhost/api/?report=join", NULL, NULL, urlQuery.c_str());
}
break;

We leave both the handler and token parameters as NULL since we don't care about whatever comes back from the URL. It could fail and burn for all we care.

URL Calls with Callbacks

Ok, what about if we do care about things failing and burning? Or what if we need the data returned from the URL? As an example, League Overseer expects to receive information back from the league website; it expects to get team information or the results of a match report. We work with the returned data in our URLDone() implementation.

Similar to our handling of slash commands, we'll comment out some of the parameters we won't actually use to prevent warnings about unused variables; we only really care about *data and complete.

In this case, the data we'll be receiving from the URL we called will be text, so we will cast it to a const char* and assign that value to an std::string to allow for easier manipulation in the future. The logic is left up to you to implement. You can output it to all the users with bz_sendTextMessage(), store it in an array, or just discard it and drive into walls.

void SAMPLE_PLUGIN::URLDone(const char* /*URL*/, const void *data, unsigned int /*size*/, bool complete)
{
    std::string webData = (const char*)data;

    if (complete)
    {
        // ...your own logic
    }
}

Most APIs nowadays supports returning data as JSON, so if you'd like to use parse and work with JSON, I've already set the ground work for it. If you use json-c, you'll likely have good support since it's available on most *nix distributions (libjson0-dev in Debian/Ubuntu; json-c-devel in Fedora Linux) and should already be installed by server owners who run league servers (League Overseer requires it). To make your life even easier, I've written a thin wrapper on top of json-c that'll save you the effort of using its complicated and tedious API: JSONObject.

You're welcome.

Using HTTP Headers

Some APIs require keys or tokens to be passed through HTTP headers, and as of today, the BZFS API supports sending headers in your URL jobs.

The first step is to create a bz_APIStringList pointer somewhere; I'd recommend declaring it in the class definition, initialize it when you configure your headers, and free it in URLDone().

If we free the list before URLDone() is called, you'll likely get a segmentation fault.
If you never delete it, you'll likely get a memory leak.
If you don't use bz_newStringList() and use a reference instead, your plug-in won't work on Windows.

bz_APIStringList *headers = bz_newStringList(); // Remember to free this!

Once we've created the string list pointer, we'll be able to set and modify headers as we please. This functionality follows the same practice as libcurl's for simplicity and familiarity.

// Remove a header curl would otherwise add by itself
headers->push_back((std::string)"Accept:");

// Add a custom header
headers->push_back((std::string)"X-ApiKey: MySuperSecretAwesomeAPIKey");

// Modify a header curl otherwise adds differently
headers->push_back((std::string)"Cache-Control: no-cache");
headers->push_back((std::string)"Host: example.com");

// Add a header with "blank" contents to the right of the colon. Note that
//    we're then using a semicolon in the string we pass to curl!
headers->push_back((std::string)"X-silly-header;");

// Make the URL call
bz_addURLJob("api.example.com", NULL, NULL, NULL, headers);

Conclusion

I apologize that this chapter didn't have a complete plug-in that we built together but I couldn't think of a quick and easy to plug-in to write that used public APIs. Depending on the demand, I may revisit this chapter with a more in-depth tutorial about using APIs and parsing JSON. However, I believe I've covered enough for you to be able to make use of URL jobs and use the returned data in conjunction with what you've learned in the previous chapters.

July 2017 Radio Silence

2017-07-24T04:00:00+00:00

If you've been following my BZFlag Plug-ins for Dummies series, you may have noticed the radio silence for the past two weeks. Don't worry, the project is still alive and scheduled to continue. The past two weeks have just been incredibly busy for me with work, summer school, and projects so I haven't had time to write any new chapters; heck even my GitHub contributions graph has been quiet. I've got a new chapter for that series planned for July 29, so don't worry you'll be able to continue writing plug-ins.

If you're curious as to why there's been radio silence, it's because I've been busy researching and learning more about web accessibility; BZiON is the guinea pig for everything I've been learning so far. You can expect a huge update to the Leagues United website by the end of the August or mid-September. One of the most anticipated features is the introduction of individual ELO ratings for players and as I promised, that's coming by the end of summer. There have been some remarks made concerning the lack of progress with this feature and my response to that is: BZiON is an open source project maintained by two people during their spare time.

Anyhow, BZiON 0.9.3 is scheduled for some time before the end of September and that's as accurate as I can be. Chapter 6 of BZFlag Plug-ins for Dummies is scheduled for next Saturday.

BZFlag Plug-ins for Dummies: Chapter 5

2017-07-08T08:00:00+00:00

After last week's pretty long chapter, this'll be shorter in comparison. So far we've written simple plug-ins where the behavior we define is all the behavior the plug-in gets. But what if we want to allow the server owners or map makers to control the behavior of the plug-ins. This can be done in several ways but in this chapter, we'll be covering using configuration files.

So what do configuration files look like?

[pluginname]
    setting1 = my value 1
    setting2 = another value

The API provides a PluginConfig object, which is available through the plugin_config.h header and this is what we use to parse configuration files for us.

Setup

When plug-ins are loaded, you can pass one parameter to it when you load it either via -loadplugin or /loadplugin.

-loadplugin messengerPlugin,/path/to/configuration.cfg

The value passed at load time is accessible to us in the Init() method as the config parameter. We can advantage of this functionality to expect the path to a configuration file when the plug-in is loaded. Personally, I like to keep all of the logic for parsing configuration files and setting things up in its own dedicated method so I create loadConfiguration(). I declare it in the plug-in's class definition and call it in the Init() method.

Tip: If you'd like to reload the configuration while the plug-in is loaded, be sure to save the config value as an instance variable in the class.

class Messenger : public bz_Plugin
{
    // ...
    virtual void loadConfiguration (const char* config);
};

void Messenger::Init (const char* config)
{
    // config = "/path/to/configuration.cfg"
    loadConfiguration(config);
}

Plug-in Specification

Now that we have declared the function and are using it, let's define what we need it to do. Now PluginConfig only works with strings but our configuration file will need to support booleans and integers too.

Heads up! Do not use quotes in your configuration file unless you would like a literal quote in the value.

[messenger]
    DEBUG_LEVEL = 0
    SEND_MESSAGES = true
    WELCOME_MESSAGE = Welcome to this server
    CAPTURE_MESSAGE = Yay someone captured...

In this plug-in that we're building, here's is what each configuration option is going to do:

Name	Description
DEBUG_LEVEL	The default debug level that will be used in `bz_debugMessage()` function calls
SEND_MESSAGES	Set to false to disable the plug-in entirely
WELCOME_MESSAGE	A message sent to players when they join
CAPTURE_MESSAGE	A message sent to everyone when someone captures

As I mentioned, all of our logic will be defined in loadConfiguration() because it's a good idea to keep things together. Additionally, we can implement functionality to reload the configuration file while the plug-in is loaded.

Let's start our loadConfiguration() method by creating a PluginConfig object, defining the section we'll be reading, and exit out if there are any errors reading the configuration file.

void Messenger::loadConfiguration (const char* configPath)
{
    PluginConfig config = PluginConfig(configPath);
    std::string section = "messenger";

    if (config.errors)
    {
        bz_debugMessage(0, "Your configuration file has errors");
        return;
    }
}

After we've created the parser and checked for errors, we can start working with the data from the configuration file but first, we need a place to store all of that data. Now, remember the previous chapter where we discussed stateful data? We'll be storing configuration data the same way. Let's create some instance variables in our plug-in's class to store the information we get from our configuration file.

class Messenger : public bz_Plugin
{
    // ...
    virtual void loadConfiguration (const char* config);

    // Plug-in configuration
    int DEBUG_LEVEL;
    bool SEND_MESSAGES;
    std::string WELCOME_MESSAGE, CAPTURE_MESSAGE;
};

Now that we have a place to store the information, let's start pulling information from our configuration file. Our PluginConfig has an item() method that we use to pull values. You may be wondering why our variables are uppercase, well that's just a convention I follow so I can easily tell what variables pertain to a configuration option and which don't. Pulling strings from the configuration file is easy, as seen below.

void Messenger::loadConfiguration (const char* configPath)
{
    // ...

    WELCOME_MESSAGE = config.item(section, "WELCOME_MESSAGE");
    CAPTURE_MESSAGE = config.item(section, "CAPTURE_MESSAGE");
}

However, pulling booleans or integers... Well that will require some conversion/logic on our part.

void Messenger::loadConfiguration (const char* configPath)
{
    // ...

    // Use std::stoi for string to int conversion
    try
    {
        DEBUG_LEVEL = std::stoi(config.item(section, "DEBUG_LEVEL"));
    }
    catch (std::exception &e) {}

    // Use a comparison for booleans
    std::string _sendMessages = bz_tolower(config.item(section, "SEND_MESSAGES").c_str());
    SEND_MESSAGES = (_sendMessages == "true");
}

As you can see, parsing a configuration file and saving the values takes a lot of work and it should belong in its own method so it can be used easily. For example, if you'd like to build in a /reload option for reparsing the configuration file, you can simply call this function instead of doing all the work several times.

Our Plug-in

Here's the majority of the plug-in we've built in this chapter. Read on to the conclusion to see which part is missing and why.

#include "bzfsAPI.h"
#include "plugin_config.h"

class Messenger : public bz_Plugin
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);

    virtual void loadConfiguration (const char* config);

    // Plug-in configuration
    int DEBUG_LEVEL;
    bool SEND_MESSAGES;
    std::string WELCOME_MESSAGE, CAPTURE_MESSAGE;
};

BZ_PLUGIN(Messenger)

const char* Messenger::Name ()
{
    return "Messenger";
}

void Messenger::Init (const char* config)
{
    loadConfiguration(config);

    Register(bz_eCaptureEvent);
    Register(bz_ePlayerJoinEvent);
}

void Messenger::Cleanup ()
{
    Flush();
}

void Messenger::Event (bz_EventData* eventData)
{
    // Read the "On Your Own" section
}

void Messenger::loadConfiguration (const char* configPath)
{
    PluginConfig config = PluginConfig(configPath);
    std::string section = "messenger";

    if (config.errors)
    {
        bz_debugMessage(0, "Your configuration file has errors");
        return;
    }

    WELCOME_MESSAGE = config.item(section, "WELCOME_MESSAGE");
    CAPTURE_MESSAGE = config.item(section, "CAPTURE_MESSAGE");

    try
    {
        DEBUG_LEVEL = std::stoi(config.item(section, "DEBUG_LEVEL"));
    }
    catch (std::exception &e) {}

    std::string _sendMessages = bz_tolower(config.item(section, "SEND_MESSAGES").c_str());
    SEND_MESSAGES = (_sendMessages == "true");
}

Conclusion

It's a good idea to allow map makers or server owners to customize the plug-in's functionality easily without having to recompile the entire plug-in each time you'd like to change the welcome message. It's a good idea to introduce a configuration file for plug-ins that have a lot of features or can be used in different settings.

On Your Own

I've been doing my best to write these chapters in an order where you build on top last chapter's lesson. So this chapter's plug-in will be left for you to complete. The necessary events have already been registered in the Init() function. Your task for this week is to implement this plug-in's Event() method that will send the appropriate messages when a capture happens or a player joins.

Updates to docs.allejo.io

2017-07-04T08:00:00+00:00

It's the 4th of July and you know what that means for me, right? It means I do my best to avoid spending time with friends and extended family. Today, I spent time improving my docs.allejo.io domain, which is used for hosting the documentation for my projects/libraries.

Here are the updates I pushed out to the domain today:

It is now served via HTTPS only
All URLs are served as lowercase and without the .html extension
- Case sensitive URLs will automatically be rewritten as lower case
- Links with .html extensions will automatically be rewritten without them
- There should be enough redirects in place to prevent any broken links but let me know if you find any
Documentation is now updated within minutes of commits to the project (if things don't break)

The domain is hosted on Netlify and the repository for the configuration of this site is available under allejo/docs.allejo.io on GitHub. I'm using Netlify's incoming webhooks with GitHub's outgoing webhooks in both the PhpSoda and PhpPulse repositories so it'll trigger a rebuild of the documentation each commit I make to these respective repositories.

There's room for improvement in this project; e.g. don't rebuild the documentation for both projects when only one project has been updated. However, it works for now!

BZFlag Plug-ins for Dummies: Chapter 4

2017-07-01T08:00:00+00:00

For those of you who think I write these chapters ahead of time, you're wrong.

In the last chapter, we went over how slash commands worked at a very basic level and today we'll be going in-depth with slash commands and stateful data.

Plug-in Specification

In this chapter, we'll be building a plug-in that allows players to respawn at the same location as a player of their choice.

When a player uses the /sneak command, they will be specifying which player's location they would like to spawn at.
If a player has used the /sneak command, their next spawn location will be dictated by the plug-in.

Stateful Data in Plug-ins

I won't go into detail what stateful data is because there's a Wikipedia page for it but I will give an example. Let's consider the following situations:

On a server, a player has been /mute'd by an admin. How does the server remember that the player cannot talk each time the player tries to send a message? This is stateful data, the server needs to remember the current state of the player and their inability to talk.
During a CTF game, we need to check if the teams are fair. We'll keep a boolean of whether or not CTF is currently enabled. This boolean will be used when checking whether or not to allow a player to grab a team flag. This is the current state of the CTF match.

This is a common requirement when building plug-ins especially to communicate data between different events, slash commands, functions, etc. This information could be thought of as "global variables," however it's still within the scope of the plug-in (they're actually instance variables). Any stateful data stored this way will remain in the server's memory. If a server were to restart or the plug-in is unloaded, then all this data would be lost.

What stateful data do we need to keep track of? We need to keep track of whom a player has specified as their target. A good number to remember is: 256; this is approximately the maximum number of player slots a BZFlag server can handle (some numbers are reserved, so it's actually less).

When we would like to keep stateful data, we'll be declaring the necessary variables in the class definition of the plug-in and initializing those variables to default values in our Init() function. We'll be storing most of our stateful data in simple arrays since they're faster than vectors or maps.

Heads up! Depending on how complicated the information you're handling is, a vector or a map may be better suited.

Let's create an array that will be able to handle information for all of our players on the server.

int sneakAttack[256];

And just like that, we've got 256 records; one for each player slot even the reserved player slots. Here's how the structure will behave:

sneakAttack[ <player ID of whom this record belongs to> ] = <the ID of the victim of this sneak attack>;

If that doesn't make sense, let's consider the following situation: Player 0 would like to perform a sneak attack on Player 5. In the above int array, we'll have the following values:

sneakAttack[0] = 5;

We'll be initializing the values for the entire array to -1, which will mean that there is no sneak attack planned yet. Why -1? Because player slots start from 0, so a negative value will be apt. This way, we won't bombard player slot 0 with a lot of sneak attacks.

Here's what our class will look like and our initialization of the array.

class Sneak : public bz_Plugin
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);

    int sneakAttack[256];
};

// ...

void Sneak::Init (const char* config)
{
    // ...

    // Range-based for loop syntax; a C++11 feature
    for (int &i : sneakAttack)
    {
        i = -1;
    }
}

Slash Command Parameters + Stateful Data

Following the plug-in specification, we'll be implementing the /sneak command and make use of the stateful data. Here's the syntax of the slash command:

/sneak <player ID | callsign>

Let's get the skeleton of the slash command implementation from our handy plug-in skeleton generator.

bool Sneak::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "sneak")
    {

        return true;
    }

    return false;
}

Remembering from last chapter, playerID is the ID of the player who executed the command and params is a list of parameters given to the command (separated by space and respecting quotes).

Let's start our implementation by saving the parameter data into an easy to remember variable.

bool Sneak::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "sneak")
    {
        const char* victimID = params->get(0).c_str();

        return true;
    }

    return false;
}

Now that we have information stored, let's get started with our implementation! So victimID stores the victim of the sneak attack, but we don't know how the player typed it in. It could be any of the following:

#0
0
my callsign

The BZFS API works exclusively with player IDs, which are integers. So what are we going to do with the above strings? Luckily for us, bz_getPlayerBySlotOrCallsign() exists exactly for this purpose. It will take whatever value the player gave us and give us one of two things we know how to work with:

bz_BasePlayerRecord*
NULL

Let's use it to get a player record of the victim or exit out if the victim doesn't exist on the server.

bool Sneak::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "sneak")
    {
        const char* victimID = params->get(0).c_str();

        bz_BasePlayerRecord *pr = bz_getPlayerBySlotOrCallsign(victimID);

        if (!pr)
        {
            bz_sendTextMessagef(BZ_SERVER, playerID, "player \"%s\" not found", victimID);
        }
        else
        {
            bz_freePlayerRecord(pr);
        }

        return true;
    }

    return false;
}

Now that we have a player record, let's set our stateful data for this player's sneak attack. This is important because this information will be accessed the next time a player spawns, which is an event, which is implemented in our Event() function. Using stateful data allows us to share information across different parts of our code.

bool Sneak::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "sneak")
    {
        const char* victimID = params->get(0).c_str();

        bz_BasePlayerRecord *pr = bz_getPlayerBySlotOrCallsign(victimID);

        if (!pr)
        {
            bz_sendTextMessagef(BZ_SERVER, playerID, "player \"%s\" not found", victimID);
        }
        else
        {
            sneakAttack[playerID] = pr->playerID;
            bz_freePlayerRecord(pr);
        }

        return true;
    }

    return false;
}

We're all done with our slash command! Let's give our slash command a try with different information.

Works as intended. Yay!
```
/sneak allejo
```
Got a message: player "callsign" not found
```
/sneak callsign with spaces
```
Got a message: player "" not found
```
/sneak
```

Ok, we definitely want some type of warning if I give the command too much or too little information. Let's fix that, the command expects one parameter so let's ensure we always have 1 parameter before we do any of our business logic.

bool Sneak::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "sneak")
    {
        if (params->size() != 1) 
        {
            bz_sendTextMessage(BZ_SERVER, playerID, "/sneak <player ID|callsign>");
            return true;
        }

        const char* victimID = params->get(0).c_str();

        bz_BasePlayerRecord *pr = bz_getPlayerBySlotOrCallsign(victimID);

        if (!pr)
        {
            bz_sendTextMessagef(BZ_SERVER, playerID, "player \"%s\" not found", victimID);
        }
        else
        {
            sneakAttack[playerID] = pr->playerID;
            bz_freePlayerRecord(pr);
        }

        return true;
    }

    return false;
}

Ok, now we're done with our slash command. Moving on...

Modification Events + Stateful Data

Our slash command will save information about our sneak attack, but now we have to make use of it during our spawn event. In chapter 2, we went over modification events and their ability to change how the server behaves. For this plug-in, we'll be modifying the spawn location of a player and will need an event relating to spawning. Here are our options:

bz_eAllowSpawn
bz_eGetPlayerSpawnPosEvent
bz_ePlayerSpawnEvent

Remember, events beginning with with bz_eAllow are modification events but there are some exceptions to the rule. If we take a look at the documention for of these events, we'll want to pick bz_eGetPlayerSpawnPosEvent since this is the only event that gives us coordinates for a player's spawn location. Additionally, there's a handled boolean, which let's us tell the server that we have modified the spawn location.

case bz_eGetPlayerSpawnPosEvent:
{
    bz_GetPlayerSpawnPosEventData_V1 *data = (bz_GetPlayerSpawnPosEventData_V1*)eventData;

    // Data
    // ----
    // (int)          playerID  - ID of the player that is requesting the spawn position.
    // (bz_eTeamType) team      - The team the player is currently in.
    // (bool)         handled   - The current state representing if other plug-ins have modified the spawn position.
    // (float[3])     pos       - Position where the player will be spawned. This value is initialized to the server
    // (float)        rot       - The rotational direction that the player will be spawned at. This value is initialized
    // (double)       eventTime - The local server time of the event.
}
break;

Now, let's write our implementation of this event using our stateful data.

case bz_eGetPlayerSpawnPosEvent:
{
    bz_GetPlayerSpawnPosEventData_V1 *data = (bz_GetPlayerSpawnPosEventData_V1*)eventData;

    // Step 1
    if (sneakAttack[data->playerID] >= 0)
    {
        // Step 2
        bz_BasePlayerRecord *pr = bz_getPlayerByIndex(sneakAttack[data->playerID]);

        // Step 2.1
        if (!pr) 
        {
            bz_sendTextMessage(BZ_SERVER, data->playerID, "Your sneak attack failed! Victim not found.");
            return;
        }

        // Step 3
        data->handled = true;
        data->pos[0] = pr->lastKnownState->pos[0];
        data->pos[1] = pr->lastKnownState->pos[1];
        data->pos[2] = pr->lastKnownState->pos[2];
        data->rot = pr->lastKnownState->rotation;

        // Step 4
        bz_freePlayerRecord(pr);

        // Step 5
        sneakAttack[data->playerID] = -1;
    }
}
break;

Step 1

Remember, a -1 value means that there isn't a sneak attack prepared so we can move on if there isn't a sneak attack planned.

Step 2

Create a player record for the victim of the sneak attack. The player record contains a bz_PlayerUpdateState object which contains the player's last known position.

Step 2.1

Remember, a player record could be NULL so we need to make sure that our victim actually exists.

Step 3

We set the handled boolean to true to notify the server that a plug-in will be changing the spawn location of a player. A player's position is denoted by a float[3] where 0 -> x, 1 -> y, and 2 -> z on a 3D coordiante system.

Step 4

Remember to free any memory you allocate!

Step 5

Set the sneak attack value to -1 so next time the player spawns, they won't be at the same victim's location unless they use the /sneak command again.

Keeping Our State Clean

An important aspect about using state data is that we need to keep it clean. It's been mentioned before that player IDs are reused when players join/part, so what would happen if Player 0 plans a sneak attack on Player 5 but leaves before they respawn? The next player who joins as Player 0 will have a sneak attack on Player 5 already without even using the /sneak command. To prevent this from happening, it's a good idea to reset state data whenever necessary.

In this case, since our state data is directly tied to each player, we'll need to reset the data each time the player leaves. We could also reset our data when a player joins and in this case example, it wouldn't matter. However, if you start keeping more memory intensive information, why bother keeping that around when a player is already gone? So it's a good idea to reset data when a player parts.

case bz_ePlayerPartEvent:
{
    bz_PlayerJoinPartEventData_V1 *data = (bz_PlayerJoinPartEventData_V1*)eventData;

    sneakAttack[data->playerID] = -1;
}
break;

Our Sneak Plug-in

Here's our whole plug-in from this chapter!

#include "bzfsAPI.h"

class Sneak : public bz_Plugin, public bz_CustomSlashCommandHandler
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);
    virtual bool SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params);

    int sneakAttack[256];
};

BZ_PLUGIN(Sneak)

const char* Sneak::Name ()
{
    return "Sneak";
}

void Sneak::Init (const char* config)
{
    Register(bz_eGetPlayerSpawnPosEvent);
    Register(bz_ePlayerPartEvent);

    bz_registerCustomSlashCommand("sneak", this);

    // Range-based for loop syntax; a C++11 feature
    for (int &i : sneakAttack)
    {
        i = -1;
    }
}

void Sneak::Cleanup ()
{
    Flush();

    bz_removeCustomSlashCommand("sneak");
}

void Sneak::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_eGetPlayerSpawnPosEvent:
        {
            bz_GetPlayerSpawnPosEventData_V1 *data = (bz_GetPlayerSpawnPosEventData_V1*)eventData;

            if (sneakAttack[data->playerID] >= 0)
            {
                bz_BasePlayerRecord *pr = bz_getPlayerByIndex(sneakAttack[data->playerID]);

                if (!pr) 
                {
                    bz_sendTextMessage(BZ_SERVER, data->playerID, "Your sneak attack failed! Victim not found.");
                    return;
                }

                data->handled = true;
                data->pos[0] = pr->lastKnownState->pos[0];
                data->pos[1] = pr->lastKnownState->pos[1];
                data->pos[2] = pr->lastKnownState->pos[2];
                data->rot = pr->lastKnownState->rotation;

                bz_freePlayerRecord(pr);

                sneakAttack[data->playerID] = -1;
            }
        }
        break;

        case bz_ePlayerPartEvent:
        {
            bz_PlayerJoinPartEventData_V1 *data = (bz_PlayerJoinPartEventData_V1*)eventData;

            sneakAttack[data->playerID] = -1;
        }
        break;

        default: break;
    }
}

bool Sneak::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "sneak")
    {
        if (params->size() != 1) 
        {
            bz_sendTextMessage(BZ_SERVER, playerID, "/sneak <player ID|callsign>");
            return true;
        }

        const char* victimID = params->get(0).c_str();

        bz_BasePlayerRecord *pr = bz_getPlayerBySlotOrCallsign(victimID);

        if (!pr)
        {
            bz_sendTextMessagef(BZ_SERVER, playerID, "player \"%s\" not found", victimID);
        }
        else
        {
            sneakAttack[playerID] = pr->playerID;
            bz_freePlayerRecord(pr);
        }

        return true;
    }

    return false;
}

Conclusion

After last week's short chapter, was this chapter long enough for you? I hope I didn't overwhelm you with too much information and that all of this made sense to you. Next up, we'll be going over configuration files.

Special thanks to the_map for being this week's guest editor!

On Your Own

If you would like to continue practicing, expand on this plug-in on your own by accomplishing the following task:

Keep track of a new bit of stateful data for each sneak attack. The new information will be a flag the player will receive when they spawn.
- Modify the slash command to be: /sneak <player ID | callsign> <flag abbv>
- Hints: bz_ePlayerSpawnEvent & bz_givePlayerFlag()

BZFlag Plug-ins for Dummies: Chapter 3

2017-06-24T08:00:00+00:00

We've both made it to chapter 3; we should be proud. You, because you've made it this far. Me, because I've been able to write this on a weekly basis without missing a day thus far. Today, we'll be talking about slash commands. Don't worry, like always, we'll be going step by step.

Slash Commands

Registering custom slash commands is pretty easy once you've got the hang of things and understand what is going on. Once again, I'll be using my plug-in generator to take care of all the generation and set up.

Extending a Class

As mentioned in the first chapter, our plug-ins will always extend the bz_Plugin class but in order to implement slash commands, we must extend one more class: bz_CustomSlashCommandHandler.

Heads up! This is an opinionated approach where all the logic is in one class. You may wish to create a separate class dedicated to handling slash command logic but I prefer keeping things together so this chapter will keep things in one class.

By extending bz_CustomSlashCommandHandler, we're required to implement the following virtual function:

virtual bool SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params);

Here's an explanation of each parameter:

playerID - The ID of the player who executed the slash command
command - The command that was executed (this is useful when you register more than one command)
message - The slash command and all of the parameters together as a string. This parameter is commented out in order to prevent compiler warnings of unused variables since message is rarely used. Notice carefully that only the variable name is commented out and not the data type.
params - A list of the parameters given to the command; parameters are split by spaces and respects quotes

Registering the Slash Command

When coming up with your custom slash commands, there are few things that you should keep in mind:

Don't accidentally override existing slash commands
Slash commands names cannot have spaces
Keep your slash commands easy to remember

We must tell BZFS that we'll be creating a custom command so the server knows that when this custom command is executed, it is forwarded to our plug-in instead of having the server attempt to handle an unknown command. To register a custom slash command called "mycommand", we call the bz_registerCustomSlashCommand() function inside of our plug-in's Init() function. Remember, the Init() function is the first function called when a plug-in is loaded, so you must tell BZFS your custom commands when your plug-in is first loaded.

bz_registerCustomSlashCommand("mycommand", this);

The second argument to this function is a reference to the class handling the implementation of the slash command, so this refers to the current class we're in. If you'd like to separate the commands into a separate class, you would use a reference to that class instead.

Heads up! Since 2.4.4, custom slash commands can override existing commands meaning that we can override built-in server commands such as /kick or /ban; more on this later on.

Removing the Slash Command

And when the plug-in is unloaded, we must tell BZFS that we'll be removing the slash command. Otherwise, the server will attempt to forward the command to a plug-in that is no longer loaded and that's just not nice. We need to call bz_removeCustomSlashCommand() the Cleanup() function, which is called when the plug-in is unloaded.

bz_removeCustomSlashCommand("mycommand");

Implementing Commands

The finally step to creating custom slash commands is implementing their behavior and what they do. We do this in the implementation of the virtual SlashCommand() function that we saw at the beginning of this chapter.

bool SAMPLE_PLUGIN::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "mycommand") // step 1
    {
        bz_sendTextMessagef(BZ_SERVER, playerID, "You ran the %s command.", command.c_str()); // step 2
        return true; // step 3
    }

    return false; // step 4
}

Step 1

The first step is to check which command got called. If your plug-in has multiple custom commands, you need to check that you're defining the behavior for the correct command and in this example, we're doing that with an if statement. Notice that command is a bz_ApiString so that means we can use the == operator for comparisons.

Step 2

We send a message to the player who executed the command and tell them what command they ran.

Step 3

Notice how SlashCommand()'s return type is a boolean? If a slash command's implementation returns true, then the BZFS will know that the command has been handled and doesn't need to do anything else. If this implementation returns false, then BZFS will attempt to take care of the implentation; this is especially useful for partially overriding built-in slash commands.

Step 4

This return statement will typically never be reached unless you have not implemented your command so it's a good idea to return false so BZFS will throw an error of an unknown command.

Our Sample Plug-in

Here's what our final plug-in looks like.

#include "bzfsAPI.h"

class SAMPLE_PLUGIN : public bz_Plugin, public bz_CustomSlashCommandHandler
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData) { return; };
    virtual bool SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params);
};

BZ_PLUGIN(SAMPLE_PLUGIN)

const char* SAMPLE_PLUGIN::Name ()
{
    return "SAMPLE_PLUGIN";
}

void SAMPLE_PLUGIN::Init (const char* config)
{
    bz_registerCustomSlashCommand("mycommand", this);
}

void SAMPLE_PLUGIN::Cleanup ()
{
    Flush();

    bz_removeCustomSlashCommand("mycommand");
}

bool SAMPLE_PLUGIN::SlashCommand (int playerID, bz_ApiString command, bz_ApiString /*message*/, bz_APIStringList *params)
{
    if (command == "mycommand")
    {
        bz_sendTextMessagef(BZ_SERVER, playerID, "You ran the %s command.", command.c_str());
        return true;
    }

    return false;
}

Conclusion

Was this chapter too short for you? Sorry about that, it's not laziness I swear! I did not want this chapter to be overwhelming with a lot of information. Stay tuned for next week's chapter where we'll be learning about slash command parameters and stateful data.

On Your Own

Exploring the list of API functions, create commands to match the following scenarios:

A slash command that will double your current score. Hint: bz_incrementPlayerWins()
A slash command that will return the current flag that you're carrying

BZFlag Plug-ins for Dummies: Chapter 2

2017-06-17T08:00:00+00:00

I told you it wouldn't take another 2 years until the next post. We're back and in this chapter we'll be discussing player records and modification API events.

Last week, I briefly mentioned player records and the fact that they'll typically be used whenever we want information regarding a player on the server. Let's go over what information is available, how to create them, how to use them, and how to free them when we're done.

Player Records

All player records are bz_BasePlayerRecord objects and they can either be created manually or are automatically given to you by the API. For example, the bz_ePlayerJoinEvent has a record attribute that is automatically created and freed for you; however, the player record will only exist in the same scope of *data as seen in the snippet below.

case bz_ePlayerJoinEvent:
{
    bz_PlayerJoinPartEventData_V1 *data = (bz_PlayerJoinPartEventData_V1*)eventData;

    // Data
    // ----
    // (int)                  playerID  - The player ID that is joining
    // (bz_BasePlayerRecord*) record    - The player record for the joining player
    // (double)               eventTime - Time of event.
}
break;

So what happens when we're in a place of our code where the API doesn't provide a record for us? We create it by ourselves. We'll be using the bz_getPlayerByIndex(int playerID) function to create a record for the player with the given player ID and we'll receive a pointer to our player record; since we're receiving a pointer to the data, we must free the record once we're done with it with bz_freePlayerRecord().

In the previous chapter, it was mentioned that player IDs were unique to players during their current session on a server; these player IDs will be used throughout your plugin. Let's create a player record for the player whose ID is currently 1.

int playerID = 1;
bz_BasePlayerRecord *record = bz_getPlayerByIndex(playerID);

Now, before we access the information in the player record, we must check that record is not NULL because bz_getPlayerByIndex() will return NULL if a player with the given ID does not exist.

if (!record) {
    // The player did not exist
    return;
}

Now that we've created the player record and have checked that it actually contains information, here's some of the information we now have access to. Take a look at the bz_BasePlayerRecord documentation to view all of the information available in each record.

name	description
playerID	...
callsign	the player's callsign
team	the current team the player is on
currentFlag	the current flag they're holding; an empty string if no flag is being held
spawned	a boolean set to true if they're alive
verified	set to true if the player is a registered account (i.e. has a `+` next to their name)
bzID	the registered player's globally unique ID
admin	whether or not the player is an admin

Since record is our pointer to our player record, we can access all of this information with the -> operator (or the . operator too).

std::string callsign = record->callsign;

// or

std::string callsign = (*record).callsign;

Now that we've stored the callsign, we're done with player record so now we must free it or else it'll continue to take up memory, a small amount but if you continue creating more records without freeing them those small amounts of memory will add up.

bz_freePlayerRecord(record);

Modification API Events

In the previous chapter, I mentioned "notification" API events and now I'm mentioning "modification" events? These aren't vocabulary words from the API, they're just what I heard from flying_popcorn years ago and so the names have stuck. What I consider a notification is an event that is used solely for notification purposes and doesn't allow you to change the behavior of the server and a modification event is an event that will allow you to control how the server behaves. Make sense? It's ok if it doesn't, we'll be building a plug-in to show you what it means.

Our plug-in will restrict which flags players can grab based on certain criteria. Let's build a ridiculous plug-in that does the following:

All players can grab every flag except GM and WG
Only registered players will be able to grab GM
Only admins will be able to grab WG

Now, let's see what event can we use to achieve this. bz_eFlagGrabbedEvent sounds perfect for the job, right? bz_eFlagGrabbedEvent is a notification event meaning we'll only be notified of when a player grabs the flag but we won't be able to prevent a player from actually grabbing the flag, since that'd require us to change the behavior of the server. Most modification events typically begin with bz_eAllow so if we look at the list of events again, we'll see that there's a bz_eAllowFlagGrab event; now that sounds like what we're looking for.

The typical server behavior is as follows: when a player drives over a flag, the server gives the player the flag. We would like to change this behavior so only some players can grab certain flags; this is where our modification event comes in. Notice how there is an allow boolean available to use in this event and how our event data is a pointer.

case bz_eAllowFlagGrab:
{
    bz_AllowFlagGrabData_V1 *data = (bz_AllowFlagGrabData_V1*)eventData;

    // Data
    // ----
    // (int)         playerID  - The ID of the player who is grabbing the flag
    // (int)         flagID    - The ID of the flag that is going to be grabbed
    // (const char*) flagType  - The type of the flag about to be grabbed
    // (bool)        allow     - Whether or not to allow the flag grab
    // (double)      eventTime - The server time at which the event occurred (in seconds).
}
break;

Since we're working with a pointer, any modifications to the event data will be seen by the server. In order to prevent the server from giving the player a flag, we need to change the allow boolean to false.

case bz_eAllowFlagGrab:
{
    bz_AllowFlagGrabData_V1 *data = (bz_AllowFlagGrabData_V1*)eventData;

    data->allow = false;
}
break;

That's it! We're done, right? Let's take a closer look at what we're doing. Whenever a player is about to grab a flag, the bz_eAllowFlagGrab event is triggered and when that's triggered, we're telling the server not to give the player the flag. Our plug-in was not meant to disable all of the flags for everyone. Let's fix that.

case bz_eAllowFlagGrab:
{
    bz_AllowFlagGrabData_V1 *data = (bz_AllowFlagGrabData_V1*)eventData;
    bz_BasePlayerRecord *record = bz_getPlayerByIndex(playerID); // step 1

    // step 2
    if (!record) {
        return;
    }

    std::string flag = flagType; // step 3

    // step 4
    if (flag == "GM" && !record->verified) {
        data->allow = false;
    }
    else if (flag == "WG" && !record->admin) {
        data->allow = false;
    }

    bz_freePlayerRecord(record); // step 5
}
break;

Step 1

As we saw in the previous section, a player record will give us access to the following information that we'll be using in our plug-in:

Whether or not the player is registered
Whether or not the player is an admin

Step 2

As mentioned previously, bz_getPlayerByIndex() may return NULL if the given player doesn't exist. In this situation, it is highly unlikely we'll ever get an event triggered by a non-existent player but let's play it safe. If we try to access information from a NULL player record, we'll get a segfault. What happens when a plug-in segfaults? The server crashes. Let's prevent that from happening by making sure we're not working with NULL.

Step 3

The flag a player is attempting to grab is given to us through the flagType variable but it's given to us as a const char*. Let's remember that this is C++ and to compare const char* values, we need to use strcmp instead of ==. For this reason, I'm assigning the data to an std::string just so I can use the convenience of ==.

Step 4

Now, this is where we have to do our checks for both the flag types and the player status. We have record->verified and record->admin, which both return true when the player is using a registered account and when the player is an admin, respectively. If we negate both of these values, we'll get unregistered account status and non-admin status.

Step 5

Remember, we need to free our player record once we're done with it. Don't leak memory!

Final Plug-in

That's it! Here's what our final plug-in will look like.

#include "bzfsAPI.h"

class FlagRestrictions : public bz_Plugin
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);
};

BZ_PLUGIN(FlagRestrictions)

const char* FlagRestrictions::Name ()
{
    return "FlagRestrictions";
}

void FlagRestrictions::Init (const char* config)
{
    Register(bz_eAllowFlagGrab);
}

void FlagRestrictions::Cleanup ()
{
    Flush();
}

void FlagRestrictions::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_eAllowFlagGrab:
        {
            bz_AllowFlagGrabData_V1 *data = (bz_AllowFlagGrabData_V1*)eventData;
            bz_BasePlayerRecord *record = bz_getPlayerByIndex(playerID);

            if (!record) {
                return;
            }

            std::string flag = flagType;

            if (flag == "GM" && !record->verified) {
                data->allow = false;
            }
            else if (flag == "WG" && !record->admin) {
                data->allow = false;
            }

            bz_freePlayerRecord(record);
        }
        break;

        default: break;
    }
}

Conclusion

Congratulations on finishing your second plug-in! As always, your feedback is welcome and appreciated! I will be more than happy to improve this series to benefit all future plug-in developers.

On Your Own

If you would like to expand on what you've learned, here some tasks for you to try and tackle on your own:

When a player is not allowed to grab a flag, send a message to that player from the server stating why they are not allowed to grab the flag. For example, if a non-admin attempts to grab Wings, send them a message saying that only admins have the privilege of grabbing the Wings flag. Same for unregistered players and GM.
Only allow your own callsign to grab the Laser flag.
Add a new flag restriction that will only allow players with an even BZID to grab the Genocide flag. Hint: record->bzID is stored as a string.

BZFlag Plug-ins for Dummies: Chapter 1

2017-06-10T08:00:00+00:00

Back in 2015, I said I'd write this series. Well, here it is. Better late than never. Right? In this first chapter, I'll be going over the structure of a plug-in while building our first sample plug-in.

BZFlag plug-ins are written in C++ and each plug-in is a class which extends the bz_Plugin base class. Moving forward in this tutorial, when the word "plug-in" is used, it refers to the class that defines the plug-in's functionality. For example, when I say there are three methods each plug-in must define I mean there are three methods that the plug-in's class must define. This should make sense as you continue to read further in this tutorial.

I have a built an (opinionated) generator, which will build the skeleton of your plugin and will take care of all the configuration of everything. For the rest of this tutorial, I'll be relying heavily on this generator.

Plug-in Core + Setup

The four methods that each plug-in must define are the following:

`virtual const char* Name ();`

This method defines the name of the plugin and what will be returned in debug messages and when /listplugins is run.

`virtual void Init (const char* config);`

This method is where all of the plug-in configuration is done and is the method that is called when the plug-in is loaded. In this method, we will need to do the following:

`virtual void Cleanup ();`

This method is called whenever the plug-in is unloaded and is where you need to:

Call the Flush(); function (to unregister your event callbacks)
Remove custom flags
Remove custom slash commands
Remove custom map objects

This method has a default implementation that calls Flush(); automatically, however it's a good idea to always create this implementation so you don't forget remove custom registrations if you add any in the future of your plug-in development.

`virtual void Event (bz_EventData* eventData);`

This method is where the main behavior (our callbacks) of the plug-in is written.

API Events

BZFlag plug-ins work (mainly) by defining callbacks for specific events depending on the purpose of the plug-in. Plugins are not limited solely to events but in this first chapter, that's what we'll be covering. If you use the plug-in skeleton generator, you'll be able to check off which events you intend to use and it'll have documentation notes for you to use with what information is available in each event.

There are events available for the majority of things that happen on a server such as a player joining, leaving, dying, capturing a flag, etc. When you build your plug-in, you'll need to plan out which events you will need.

Building a Plug-in with Notification Type Events

I will be taking you through on building a plug-in that will notify unregistered players why they cannot speak. This is a hypothetical plug-in that will be used on servers where only registered players are allowed to speak.

1. Naming Your Plug-in

What's in a name? This name will be used in debug messages and /listplugins so what you return is up to you. I've adopted the practice of using the following pattern in my plug-ins:

<Plug-in Name> <Major>.<Minor>.<Revision> (<Build>)

Why so explicit? My plug-ins are never perfect the first time around and I always add more features, so I'd like to know which version is currently loaded on a server.

const char* ChatNotifier::Name ()
{
    return "Chat Notifier 1.0.0 (1)";
}

2. Registering Events

The first step in building the plug-in is to notify the server which events we'll be listening to when the plug-in is loaded. We do this in the Init() method and will register the events we want to listen to using the Register() function.

For this plug-in, we'll be listening to bz_eRawChatMessageEvent, which is called every time a player sends a message before any filtering and permission checks occur.

void ChatNotifier::Init (const char* config)
{
    Register(bz_eRawChatMessageEvent);
}

3. Defining Behavior

After we've specified to the server that we want to listen to this event, we now have to define what needs to happen when that event is triggered; we do this in the Event() method. In this method, we'll be defining the behavior for all of the events we're listening to so I'll be using a switch block to handle the behavior for each event (only one event in this plug-in's case) but I can also use an if statement.

Using the plug-in generator, here's what I've got as the definition for our Event() method. For each event, we're given a bz_EventData object that we can cast into more specific objects based on the event. Some events are used for notification purposes only and do not have any objects you can cast bz_EventData to; for bz_eRawChatMessageEvent, we're given bz_ChatEventData_V2.

void ChatNotifier::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_eRawChatMessageEvent:
        {
            bz_ChatEventData_V2 *data = (bz_ChatEventData_V2*)eventData;

            // Data
            // ----
            // (int)             from        - The player ID sending the message.
            // (int)             to          - The player ID that the message is to if the message is to an individual, or a broadcast. If the message is a broadcast the id will be BZ_ALLUSERS.
            // (bz_eTeamType)    team        - The team the message is for if it not for an individual or a broadcast. If it is not a team message the team will be eNoTeam.
            // (bz_ApiString)    message     - The filtered final text of the message.
            // (bz_eMessageType) messageType - The type of message being sent
            // (double)          eventTime   - The time of the event.
        }
        break;

        default: break;
    }
}

So here's the logic that we'll be following in this plug-in:

Get a player record for the player who sent the message
Does the record show the player is registered?
1. If not, then send them a message
Delete the player record to free memory

bz_ChatEventData_V2 *data = (bz_ChatEventData_V2*)eventData;
bz_BasePlayerRecord *pr = bz_getPlayerByIndex(data->from); // step 1

// step 2
if (!pr->verified) {
    // step 2.1
    bz_sendTextMessage(BZ_SERVER, data->from, "Register an account on forums.bzflag.org in order to talk.");
}

// step 3
bz_freePlayerRecord(pr);

Now, let's break things down further.

Step 1

If we want information regarding an individual player, we'll often need to create a player record with the bz_getPlayerIndex() function, which returns a pointer (meaning we'll need to free this pointer in step 3). In this case, we want to create a record for the player who sent the message and as we can tell from our handy documentation, data->from is the player ID who sent the message.

The player ID is not a universally unique ID for the player across all servers but it's unique to the player during their current session. Once a player leaves and someone else joins, the new player will likely take on this ID. Also if the player rejoins, they'll like get a new ID too. If you'd like to uniquely identify registered players, use pr->bzID. You may also use pr->ipAddress to identify players uniquely to some extent but it isn't always reliable (e.g. players on the same Wi-Fi network would share the same IP).

Step 2

Our player record has a boolean value verified, which is set to true if a player is registered and false otherwise. We use an if statement to check if a player is registered and negate that value.

Step 2.1

We use bz_sendTextMessage() to send a message to the player who just tried to talk. The BZ_SERVER value is a constant available to plug-ins to trigger actions on behalf of the server. In this case, the server will be sending a private message to this user.

Step 3

Lastly, we need to free the player record we created in step 1 to free the memory we've been using; there's no garbage collector around here.

4. Cleaning Up

We need to define what needs to be cleaned up when the plug-in is unloaded. When a plug-in only registers event listeners, we simply call Flush().

void ChatNotifier::Cleanup ()
{
    Flush();
}

5. Final Plug-in

Here's what the final plug-in would look like with a special note about BZ_PLUGIN().

#include "bzfsAPI.h"

class ChatNotifier : public bz_Plugin
{
    virtual const char* Name ();
    virtual void Init (const char* config);
    virtual void Cleanup ();
    virtual void Event (bz_EventData* eventData);
};

// This is a macro defined by the BZFS API which registers this plug-in. It's not
// a function, therefore the lack of semi-colon here is NOT a typo.
BZ_PLUGIN(ChatNotifier)

const char* ChatNotifier::Name ()
{
    return "Chat Notifier";
}

void ChatNotifier::Init (const char* config)
{
    Register(bz_eRawChatMessageEvent);
}

void ChatNotifier::Cleanup ()
{
    Flush();
}

void ChatNotifier::Event (bz_EventData* eventData)
{
    switch (eventData->eventType)
    {
        case bz_eRawChatMessageEvent:
        {
            bz_ChatEventData_V2 *data = (bz_ChatEventData_V2*)eventData;
            bz_BasePlayerRecord *pr = bz_getPlayerByIndex(data->from); // step 1

            // step 2
            if (!pr->verified) {
                // step 2.1
                bz_sendTextMessage(BZ_SERVER, data->from, "Register an account on forums.bzflag.org in order to talk.");
            }

            // step 3
            bz_freePlayerRecord(pr);
        }
        break;

        default: break;
    }
}

Conclusion

Congratulations! You've just completed your very first BZFlag plug-in! Don't worry, there's a lot more of the API to cover and more posts to come; this time, the next post won't take another 2 years.

Your feedback is most welcome and appreciated! However, please do not request what you'd like to see written next. I'll be writing these posts in the order I deem best.

I hate Fridays

2017-03-31T08:00:00+00:00

So Fridays are typically my days off from work and school; they're awesome and I'm always looking forward to them. However, this morning I woke up to a not so awesome Friday. Everything on my computer had crapped out.

Everything is "Damaged or Incomplete" on macOS

"Terminal.app" is damaged and can't be opened. Delete "Terminal.app" and download it again from the App Store.

Well. WTF? Right? Now, this happened for literally all of my applications. I couldn't open Disk Utility, Terminal, Chrome, Safari. Anything. So, what did I do fix this? I logged in to my secondary admin account and had to delete my account but I kept the home directory. I then recreated the account using the existing home directory. After this, it magically fixed this. Yay. Moving on to the next issue.

Homebrew's Broken

Alright, so what else is broken? Well, brew. I can run brew install and brew search however, I couldn't use brew doctor or brew uninstall and that's problematic. Here's a snippet of the error message.

Error: 757: unexpected token at ''
Please report this bug:
  http://docs.brew.sh/Troubleshooting.html
/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/lib/ruby/2.0.0/json/common.rb:155:in `parse'
/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/lib/ruby/2.0.0/json/common.rb:155:in `parse'
/usr/local/Homebrew/Library/Homebrew/tab.rb:62:in `from_file_content'
/usr/local/Homebrew/Library/Homebrew/tab.rb:57:in `block in from_file'
/usr/local/Homebrew/Library/Homebrew/tab.rb:57:in `fetch'
...

So. How did I fix this? Ugh. Fuck my life. Took me a while to finally think of this and figure out what the hell was going on but I managed to fix it by doing the following:

I modified this file /usr/local/Homebrew/Library/Homebrew/tab.rb:62 and added a puts path as the first line of self.from_file_content(content, path). I wanted to know what file was causing this to fail.
This will list all of the files that are being processed and the last file listed will be the one that's failing (though there may be more). It's a INSTALL_RECEIPT.json file that was causing me the issue with some invalid JSON somehow getting put in there.
I could either fix the JSON file if it was easy to fix, however it wasn't so I deleted the folder for that package and used brew install to reinstall it.
Last step, remove the puts after I've fixed all the broken packages.

IntelliJ IDEs failing

Lastly. All my IntelliJ IDEs began failing. Ugh. FUCK. This was the error that I was getting.

#
# A fatal error has been detected by the Java Runtime Environment:
#
#  SIGBUS (0xa) at pc=0x0000000114d909b3, pid=856, tid=0x000000000000f20f
#
# JRE version: OpenJDK Runtime Environment (8.0_112-b13) (build 1.8.0_112-release-736-b13)
# Java VM: OpenJDK 64-Bit Server VM (25.112-b13 mixed mode bsd-amd64 compressed oops)
# Problematic frame:
# C  [libFontParser.dylib+0x29b3]  TSFNTFont::GetFormat() const+0x5b
#
# Failed to write core dump. Core dumps have been disabled. To enable core dumping, try "ulimit -c unlimited" before starting Java again
#
# If you would like to submit a bug report, please visit:
#   http://bugreport.java.com/bugreport/crash.jsp
# The crash happened outside the Java Virtual Machine in native code.
# See problematic frame for where to report the bug.
#

Now, I couldn't find a fix for this solution. The only way I was able to fix this was a clean install of macOS, just the base system; i.e. I didn't wipe any content or my disks.

Overall

I was really hoping for a productive Friday with a proof-of-concept project I started working on this week... But I guess being productive today wasn't for me.

A Jekyll TOC without Plugins or JavaScript

2017-02-03T08:00:00+00:00

So on Tuesday, I was on #jekyll like any other day and a user by the name of misty came in asking about using {:toc} in a Jekyll layout instead of a markdown file. It makes sense, on large websites with a lot of markdown files, you don't want to make sure you include {:toc} in each document and if you do manage that, you're restricted with where it will be rendered—alongside the content. There's another problem with {:toc}, it won't work separately from the markdown file because Jekyll doesn't give Liquid the raw markdown so you can't prepend {:toc} and markdownify the combination nor can you combine {:toc} with HTML. I'm well aware that there are several Jekyll plugins out there and JavaScript solutions to this problem but there are two problems with each:

A Jekyll plugin will not run GitHub pages
A JavaScript solution is slow and useless if the user doesn't have JavaScript enabled

TL;DR

Drag and drop the code snippet that is available on GitHub into your repository: allejo/jekyll-toc.

Overview

Now I've been working with Liquid for a while and from first hand experience, I've come to realize that this quote accurately describes my experience with Liquid.

...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way

- jaybe

Now, why am I speaking about Jekyll when I'm working on my own static site generator and even ported my website to use my tool instead of Jekyll? Well... Because I got bored and wanted to see what I could come up. Besides, I never said that I had stopped working with Jekyll sites entirely. Anyhow, I came up with the following Liquid snippet that can easily be used as an {% include %} for any Jekyll site. Want to see it in action? It's already being used on the docs.docker.com website and the UK Ministry of Justice Technical Guidance site.

A Liquid solution to generate a table of contents for each markdown file seems like it would be slow and it actually might be compared to a plugin solution, but compared to the overall speeds of building the current Docker docs site (~2 minutes), it's really not slow at all; there are other files that are eating up more performance than the TOC builder (at the time of writing this, they're currently working on optimizing things).

Filename                                          | Count |      Bytes |    Time
--------------------------------------------------+-------+------------+--------
_includes/tree.html                               |   817 | 289571.48K | 225.508
_layouts/docs.html                                |   817 | 114017.42K |  90.628
allpagelinks.md                                   |     1 |    112.33K |  19.170
_includes/toc_pure_liquid.html                    |   813 |    524.17K |   6.422

So I've tailored this solution to not depend on any specific front matter or _config.yml setup meaning all you have to do is drop in this snippet to the _includes folder of your Jekyll site and {% include %} it with whichever parameters you want, and it'll just work.

What if you want to configure this snippet from your _config.yml or front matter? Well that's cool too but do it in your layout instead of this snippet. The goal is to keep this snippet as independent as possible so you can easily reuse it or update it and have things continue to work with any Jekyll site. As an example, in one of your layouts this is what you can do:

{% assign my_min = page.toc_min | default: site.toc_min | default: 1 %}
{% assign my_max = page.toc_max | default: site.toc_max | default: 3 %}

{% include toc.html html=content sanitize=true h_min=my_min h_max=my_max %}

Yup! You can daisy chain default filters to ensure you get some value. In this case, we're looking for a front matter value of toc_min first and if that's not set, use the toc_min defined in your _config.yml and if that's not defined, just use 1.

How It Works

The rest of this article explains how the jekyll-toc project works at a fundamental level. It is not designed as a step-by-step tutorial for how to use the above snippet; see the GitHub README for that.

This snippet is designed to work with markdownify-ed HTML given to us by Jekyll. Due to the way Jekyll was designed, you can't access the unrendered markdown of a document and are stuck with HTML.

Step 1

The very first step is to find all of the headings in the given HTML. To do so, I start off by spliting the HTML at every <h. This is my way of cheating and finding all of the headings in the given HTML and now we have an array that looks like this:

[
    '1 id="heading-1">Heading 1</h1><p>....</p>',
    '2 id="hello">Hello</h2><p>...</p>'
]

Step 2

At this point, I loop through each array item (I call it a 'node' in the code). I slice the string to get the first character, which is the heading level. I then do some Liquid magic to cast the sliced string into an integer by multiplying the string by 1.

Step 3

Now that we have the heading level as an integer, respect the h_min and h_max parameters and toss any headings we don't want by moving on to the next node if necessary.

Step 4

Now, I split each node at the </h and only keep what's on the left side of the split. So now I have an array of nodes that look like this.

[
    ' id="heading-1">Heading 1',
    ' id="hello">Hello'
]

Step 5

I now split the nodes by " and I access index 1 of that split, which will give me access the generated ID for that heading (thank you kramdown for this); i.e. heading-1 and hello.

Step 6

Now that I have the heading level and the ID, it's time to extract the actual heading content. So I build what the node looked like in step 4 up until the >, and replace it with nothing. Voilá. I've extracted the heading content.

Step 7

This project has since been rewritten to use a new algorithm (the same one stakx uses internally), making it more robust. Steps 7 and 8 remain here for historical purposes but the current version of the project no longer uses the approach explained in these steps.

Now that we have all the necessary information, all we have to do is actually build the TOC. Here's the trick, we build our TOC using markdown (e.g. - [text](#id)). I take the heading level for the current node, and subtract one. I then take that value (X) and repeat 2 spaces X times; this serves as our indentation.

For example, for our h2 becomes 2 - 1 = 1. Then I repeat 2 spaces 1 time. So our generated markdown would look like this:

- [Heading 1](#heading-1)
  - [Hello](#hello)

Step 8

Lastly, now that we have a markdown version of the TOC with the correct indentation, we markdownify it and output that. And, that's it! Pretty cool, right?

Project Repository

I originally shared this code as a GitHub Gist, however I made a promise months ago regarding this code. If I got bored enough, I'd move the code to its own repository; and so I have: allejo/jekyll-toc. Heck, I even added unit tests to show sample usage and make sure that it works as intended. Don't worry, the snippet's still under BSD-3.

Updates

2021-12-30 - Updated post with notices about outdated information and it not being a "how to" tutorial
2017-09-07 - Updated post with an overview of how the code works and updated links to the new GitHub repository

It's 2017

2017-01-15T08:00:00+00:00

Welcome to a new year. Only 15 days late but, whatever. Looking back at 2016, it was a pretty awesome year for me with regards to all of the projects I participated in. Here are some of my projects and accomplishments for 2016:

BZiON had its first major release after 2.5 years of development
stakx development began and reached its third beta with an incredible amount of features and bug fixes
Published web analytics for the City of Santa Monica and automated the whole process
Wrote my first Jekyll plug-in
Participated in my first Hacktoberfest

Starting on Dec 31st, 2016 and continuing into the first week of 2017, I spent my time rewriting my BZFlag plug-in starter to be entirely JavaScript based (where the first version was a PHP script). I decided to tackle code generation in a object oriented approach by writing the library of that website in TypeScript and wrote the UI using Vue.js—two things I had been wanting to learn/experiment with. TypeScript definitely makes writing object-oriented JS easier but one thing I really struggled with was the differences between ES5, ES6, ES2017, Babel, synonyms; the amount of jargon that exists in the JS world... It was a nightmare for me to get a grasp of things.

So what do I have planned for 2017? I definitely want to get more adept with JavaScript and TypeScript. I also really want to do more work with C#, C++, and Python. Lastly, I want to attempt to build my own lexer simply for the experience.

Thank You, AS

2016-11-19T08:00:00+00:00

I'm often curious to see other people's personal websites and am disappointed when I notice that their websites are dated or unmaintained. The pot calling the kettle black, huh? My personal website has become the most neglected project I maintain but I plan on changing that. I intend on writing more often, hence this post.

I'm known for having a pessimistic view on education and while that hasn't changed, I've started to appreciate the college experience a bit more. I'm starting my 5th year of college and I'm about to hit my third year working at CSUN's Associated Students. Soon after I started college, I took some time off and then was a part time student for a while because I simply wanted a break, something I hadn't had since what feels like middle school.

Because of my time off from college, I was still a freshman when I saw a job opening for a student web developer position posted in the computer science Facebook group I was a part of. I filled out the application and submitted it on a whim but I didn't expect anything to come of it. I had already submitted an application to a previous department on campus but I never even got a confirmation so I figured this application would be the same way.

Shortly after, I got an email to schedule an interview with my future boss, Kevin. The email stated to have a portfolio so I worked on my website really late into the morning the day of my interview. Now, what really pisses me off was that my portfolio was never even mentioned nor looked at during the interview. God damn it. I could have been sleeping instead! But. Whatever.

Maybe about a week later, I was hiking with a friend when received the following email from Kevin,

Dear

Thank you for your interest in the Web Design Student Assistant. I am delighted to offer you the position if you are still interested...

Notice how there's no name after "Dear..." I didn't know whether to get my hopes up or not so I sent a reply asking for clarification. I got nervous when I didn't hear back from Kevin soon; I thought maybe I came off as if I were mocking him. Turns out my reply wasn't sent until I came down from the trail. Apparently, trees and bushes don't make reliable Wifi hotspots. Who knew?

Shortly after, I got the following response.

Yes, it was!!! I misspelled your name and accidentally erased it rather than correct it.

Sigh... After knowing and working with Kevin for 3 years, I can look back at this and know for a fact, that this is totally something he would do.

In my three years with AS, I have made a lot of friends and have learned so much from my coworkers. Working in an office with graphic designers has taught me so much about what makes a good design and I've been able to apply that knowledge to designs I've worked on myself. I've also been able to experiment a lot with different projects and learn what's best without being too worried about breaking everything. What sucks the most is that I've been in the office for so long that I've seen many people come and go; frankly, I miss a lot of them (some more than others) and all the fond memories I have with them.

Watching friendships get brutally destroyed over a game of Munchkin
Browsing Imgur late at night laughing at the stupidest of posts
Playing Borderlands 2, FIFA, Minecraft, Rock Band, UFC, and Yu-Gi-Oh in the office after-hours
Pulling off pranks and getting IT involved because they think I broke something
Playing Cards Against Humanity after-hours
Changing the browser's default font to Comic Sans on one of the graphic designer's computer (she found it funny)
Going to Disneyland for an office retreat
Printing out a flight ticket on our large poster printer (on accident)

I still have some time before I graduate and leave AS but as I was reflecting on my college experience, AS has definitely made me hate college a little less. I'm thankful to my boss and all of my coworkers who have made this experience more fun.

Welcome Stakx

2016-11-18T08:00:00+00:00

A while back, I mentioned that I was working on my own static website generator and that I was going to post about it later. For the past 6 months, I've been working on Stakx on and off and I've finally reached a point where I can easily and efficiently build a website with Stakx.

My personal website is actually the third website I've built with Stakx; the first website was the Associated Students' Sustainability Center website. I've been wanting to redesign my website and continue building upon it so it could serve as my portfolio for my work for quite some time now, so in honor of Stakx becoming usable, I'd like to introduce my completely redesigned website! In addition to the new design, I've gone back through my previous posts and have updated them to work with Stakx or removed some of the more sillier posts; not that many people read my posts or would care.

So why exactly did I build yet another static website generator? Well of all the more popular generators out there, each one that I've tried has had shortcomings whether it's the template engine or the organization the generator expects. I didn't write Stakx as a tool that will replace Jekyll in my life, but more so as an alternative to the available tools already out there. I wanted a tool that used a powerful template engine, doesn't require a package manager to build a website, and can be distributed as just a single executable.

Stakx vs Jekyll

I'll be writing a more in-depth document regarding the differences between Stakx and Jekyll on the official Stakx website but here are some things I immediately ran into as I was porting over my website to Stakx.

No `{% post_url %}` tag

Jekyll has this Liquid tag available to reference other posts, but Stakx does not have this and it's not an oversight on my part when I was designing it. A link to another collection item can be achieved with Twig alone. In addition, you're not limited to just accessing other posts and their links, you can access any Content Item from any Collection and access all of their attributes.

{{ url(collections.posts['file-name-without-extension'].permalink) }}

I admit, not the most elegant method of accessing the permalink of another Content Item, but it is functional. In addition, Twig allows you to define macros, which is similar to Jekyll's include functionality, to create a shortcut of sorts to access permalinks with less markup.

{%- macro item_url(collection, file) -%}
    {{ url(collections[collection][file].permalink) }}
{%- endmacro -%}

{{ _self.item_url('collection-name', 'file-name-without-extension') }}

No `{% gist %}` tag

There is no custom Twig tag to fetch a GitHub Gist's content and embed it on the page at compile time without the need of having JavaScript enabled for your website readers. GitHub, however, does let you embed Gists on your page by simply pasting a script tag with information such as your GitHub username and Gist ID.

<script src="https://gist.github.com/:username/:gist-id.js"></script>

Twig plug-ins?

I do have plans for supporting custom Twig filters and tags by adding support for extending Stakx but that will have to wait for a future release.

Will both of these features be written and supported as plug-ins?
Probably.
Will these become part of Stakx core?
Possibly, being able to reference other Content Items is important and it should be an easy task for users

Moving Forward

I have learned a lot by building Stakx and there is a lot I can still improve on, such as using dependency injection instead of explicitly passing objects. I have every intention of continuing to develop and support Stakx for the forseeable future. However, Stakx is still very young so I don't think porting a large existing Jekyll website, for example, to a Stakx website would be worth the effort. At the moment, I'd recommend Stakx to be used for new small scale websites or for experimentation.

If anyone discovers Stakx and builds a website with it, I would love to know! Leave a comment on here or give me feedback by creating an issue on GitHub.

My Experience with the Youth Tech Program

2016-08-15T00:00:00+00:00

I've been wanting to write about the Santa Monica Youth Tech Program (YTP) for quite some time and what my experience was like as a participant in 2012 and now as a staff member. After searching for posts regarding YTP, all I could find were articles written by program partners and guest presenters.

I hope that an uncensored, unedited, and unofficial post will be beneficial to future participants. For that reason, I decided to post this on my personal blog because I would like to speak about my experience and thoughts without being interrupted or having my words rephrased by someone else.

Before I discuss my experience, here are some things to keep in mind:

For those of you who know me, I'm brutally honest when I can be; therefore, this post will be nothing but honest.
Even though I'm a staff member at the time of writing this post, everything I say are my own opinions and experiences that should not be treated as statements on behalf of YTP.

The very first thing I want to address is an extremely common misconception that I had as a participant and have heard from several participants during my time as a staff member. Even though the program has the word "technology" in the name, you should not go into the program thinking that all you will be focusing on and learning about is technology. YTP is a summer program where teams of participants will create start-ups, this means that all participants will learn the basics of business, graphic design, and web development. It's similar to college where you will have enough theoretical knowledge to continue your start-up but you can only learn so much without first-hand experience. If you are like me, who was expecting a programming bootcamp, then this program is definitely not for you.

For the ladies, Girls Who Code is an amazing program you should look at and definitely be a part of
For everyone, iD Tech Camps is another awesome program that I would have liked to join if I could have

Truthfully, if you're interested in the web development portion of the program, chances are you will just be learning the basics of HTML, CSS, and some JavaScript to build a website that looks like it works. Here are some things to keep in mind:

Time is extremely limited throughout the program, so it's shared between two other topics as well. This means you will be doing a lot of research and self-teaching.
Web dev presentations are taught at a pace where someone with no prior coding experience will be able to follow along. If you have prior experience, this will be too slow for you.
Building a fully functional back-end to the website will require a lot of self-teaching or prior knowledge because there is not enough time during the program to do both front-end and back-end development.

Even though I'm advertising and recommending other programs, I encourage you to read on before you decide to cross out YTP from your possible summer programs.

All throughout high school I dedicated time to teaching myself how to code and it was well worth it. In order to learn to code, I had to spend a lot of time in front of a screen and my parents weren't fond that I spent so much time on the computer "talking with strangers." I was called into my school's dean office one day and I was wondering what I had done this time to get in trouble but to my surprise, he was recommending this program to me. I had the misunderstanding that it was going to be an internship at City Hall regarding technology and so I applied and got accepted.

To my disappointment, it wasn't the coding or technology bootcamp I had imagined but it was definitely a great experience for me regardless. I was able to make some really great friends during the program and I actually learned some business concepts, which have now become common sense to me. I never thought I would have actually enjoyed a basic understanding about how businesses work, but I did. I can't do finance or write business plans, but I can definitely think of the direction a business should take and why that'd be the appropriate decision; I can now apply this knowledge to projects that I lead. I can also give feedback to my college classmates who really want to create the next Instagram but with triangular pictures instead of squares!

To this day, I am still the only participant who was able to write a fully functional website from scratch. In 2012, there weren't any web development lectures or teachers; all I had was a book I had checked out from the Santa Monica Public Library (which I still owe a late fee for...). I was only able to achieve this because I had prior experience with writing code and I made this program into my own bootcamp by dismissing the majority of business lectures and a lot of late nights. Even though my code for this website was horrendous, I was still able to impress a few web developers from the web development team at City Hall. One of these developers is now my mentor who has taught me an incredible amount and the other is now my manager. I would have never been able to work with them, let alone meet them, if it were not for this program. I simply cannot express my gratitude as words to accurately describe how amazing an opportunity I was able to get because of this program.

Going back to why I mentioned my parents not being fond of me being in front of a computer so much, it wasn't until after this program that other people praised me for my potential and knowledge that my parents actually believed that I was doing more than just wasting time on a computer. Shortly after, my parents researched average yearly income for developers and suffice to say, they supported me fully after that.

The program is still very young and will require some time to mature; after all, it just barely completed its 5th year on July 21st, 2016. At this point, the program is run solely by alumni with a few staff members being the original founders of the program; this is both really impressive and harmful. The reason I believe it's become harmful is because I feel the program has reached a plateau of innovation where change is now frowned upon because "it's always been done like this" and the alumni writing the curriculum for the program are heavily influenced by prior years. I believe a fresh pair of eyes would greatly benefit the program making it better for next year's participants. For example, it's now my 3rd year writing the web development curriculum from scratch because I have not been satisfied with it previously. While this year's curriculum was much better than prior years, I was not satisfied with how it was planned out because subconsciously, I still mistakenly treat YTP as a coding bootcamp. I have requested that someone else write the curriculum for next year but to my dismay, my curriculum for this year has been saved in the staff archive so it can be "used as a reference, if necessary."

As I mentioned, the program has become very set on its ways and change won't come about easily. If you plan on joining this program, be careful with what category you place yourself under: business, development, or graphic design. There have been several participants who have chosen a category on a whim and have come to regret their decision because they chose a category they are not interested in. The teams are chosen based on the interests you specified and what presentations you participate in during the first week; once you've classified yourself there's no going back. There have been several participants who became really interested in web development after they experienced the first few lectures but they had to continue working on the business tasks assigned to them. By not allowing participants to switch their roles, we are ensuring that a team is not dominated by all business people, for example. While I agree with this policy, it does affect morale and lessen productivity, which isn't something I would want for a summer program intended to be a fun learning experience.

If you're going to take away anything from this post, I hope it's that if you're going to go into this program, you should expect that you will be learning a little bit of business, graphic design, and web dev regardless of your preference or how boring a specific topic may be. In other words, even though you are in love with business you will still need to sit through coding and business lessons; hey, you never know what you'll find interesting.

Evidently I have a life

2016-03-08T00:00:00+00:00

I have spring break coming up in about 2 weeks; while that would typically have me excited, I'm too distracted and drained for any unnecessary emotions. I've been in a rather odd slump the past few months with where I'm at.

In just the past two months or so, I've been working on projects that I'm actually quite proud of and will continue to maintain and work on:

alezakos and I had been working to finally get BZiON 0.9.0 released on February 21st along with Leagues United—the new unified BZFlag league. This project finally sees the initial release after about 2 years and 6 months of development.
bzElectron has reached version 0.1.1 with some minor new features and an awesome pull request from alezakos to support regular group files.
At one of my current jobs, I started PhpPulse—a wrapper for the DaPulse API. The wrapper has finally reached it's initial release after a few alpha releases and has received a description of "awesomeness" by DaPulse' Twitter account.
I have also started stakx (my own static website generator), just like Jekyll, but mine's written in PHP and uses Twig—a far more powerful alternative to Liquid. I intend on using this at my current job to start building more powerful static websites, if that makes sense. There's a lot more to come regarding this project.

I am really proud about my achievements above, but that hasn't been enough for me to feel satisfied or content.

As much as I care about these projects, they simply aren't very significant to anyone else except myself and a handful of people. While I'm ecstatic about the fact that a handful of people use it, I'm saddened that I haven't been able to join or contribute to a larger community or project.

I have always taken objection to school and its practices, but that's a rant for another day. I'm taking 6 classes this semester and I'm only enjoying 2 of those classes—a Linux class and a GIS class; I've learned an incredible amount in those classes and am very happy about taking those professors. The downside? Very little of the knowledge that I've picked up is applicable to either of my current jobs or have been things that I'm already familiar with.

The worst feeling that I've been having lately, and has probably contributed to my current mood, is having a lot go over my head and not being able to learn it quickly as I have with pretty much everything else. The fact that I am having to learn a lot of these new things in an environment with deadlines is far from ideal. In addition, there are a lot of people I admire and respect who have been able to learn these concepts or tools very easily. Of course, everyone always tells me not to compare myself to others but it's hard not to, sometimes.

Anyhow, I didn't mean for this become a rant like other blog posts I've written so I'm very excited to get an early version of Stakx built and distributed to a few people to have them give it a shot to compare it to Jekyll or Sculpin.

Clickbait — You won't believe what I've seen!

2016-01-20T00:00:00+00:00

For those of you who don't know me, my sense of humor is quite cynical, sarcastic, and satirical at times. The number one thing I absolutely loathe when scrolling through my newsfeed—whether it be Facebook, LinkedIn, or Twitter—is seeing clickbait. Ok, on Facebook or Twitter it's to be expected but on LinkedIn also? These are three titles of articles I saw on LinkedIn before I quit my browser:

"This is the worst part about the new Apple TV"
"How a small design tweak got millions more people to use one of Facebook's products"
"Apple is slightly more diverse than it was last year"

Seriously... What do any these titles tell me about the respective articles?

Article #1 - This article tells me the author is bitchy and took objection to a single feature of the new Apple TV and now anyone who is searching for the pros and cons behind the new Apple TV will find this author's whiny opinion. This article is showing up on my LinkedIn because I follow Apple. Seriously LinkedIn? I expected serious articles regarding a company I choose to follow, not some whiny clickbait.

Article #2 - This sounds like those male enhancement pill emails that you receive in your spam folder. Must I say more? If your article is that boring that you must resort to sounding like a Viagra ad, reconsider your website's mission because I'm sure porn websites already have that nailed down.

Article #3 - Alright, I'll admit that the title of the article is actually more appropriate than the previous two but really? There is an entire article regarding how a single company is "slightly" more diverse than the previous year? Instead of talking about a single company's leadership, maybe you should be analyzing this trend in a specific country or around the world; something that, you know, requires actual research or journalism? Oh you're probably not capable of that, sorry.

I find it extremely disappointing that websites like Business Insider and Washington Post (the websites where these articles are housed) are becoming no better then Buzzfeed, Clickhole, or The Onion where clickbait is their thing because it's either their style or it's satire.

In conclusion, I love satire. For those of you who find my humor hard to understand, I purposely formatted this post to be like every other clickbait article I see. If your website is resorting to using clickbait to get people to read your articles simply to get ad revenue, you seriously need to reconsider your writers' abilities and your business strategy.

"How did you learn all of this?"

2015-11-21T00:00:00+00:00

Since I've started taking more computer related classes and have met some pretty cool people, the most common question I keep getting is: "how did you learn all of this?" As a friend pointed out a few days ago, I've been fooling around with code and technology for almost a decade now; I'm not entirely satisfied with the progress I've made, since I wish I had time to learn so much more.

Quite frankly, I can never really figure out how to answer that question. I always just say, "I got bored so I looked it up." This is exactly what I did but it doesn't really give you any detail as to my process. Looking back at my past, I don't really know what I did. I started by playing BZFlag and was curious how a specific developer did all that he did. I wanted to be just like him, so I asked him to teach me some basics. He pointed me to learning Perl—dear god, I know—and sent me links to tutorials via AIM. At this point, websites like Codecademcy may have existed but coding did not have the hype it has now so I didn't know of any such resources. I had a lot of trouble getting started; it took me 3 separate attempts to actually get the hang of coding. I bothered this developer a lot; and I mean a lot.

After I got the hang of some basics in Perl, I gave C++ a shot and picked it up fairly quick, or so I felt. I didn't know what loops, conditionals, classes, or any of that was. I simply would look up things like, "if this is true, do this if not do this in C++" or "how do i do something several times in C++." It wasn't until months later that I actually began learning vocabulary and my Google searches improved.

I then got into server adminstration when I started running a BZFlag server; I started off maintaining BZFMaps. My process for learning how to manage a Linux server wasn't much different at all, I kinda just started looking up what SSH was and what commands meant. Then I would search how to do things in Linux or I would copy paste error messages.

I guess you could say I kinda dove into the deep end and then searched how to swim. You have no idea how much I have fucked up on a production server. I have...

firewalled everyone (including myself)
executed sudo pkill sh
made servers non-responsive
run a fork bomb
shutdown a remote server (not reboot...) without a UI to boot the server

Oh man, those were fun times. On the bright side, I now know how to get out of those sticky situations and no longer make the same mistakes!

To be honest, I don't know how I learned all of this. I just recently started picking up Python and have written some scripts. My friend asked me how I learned Python and quite frankly, I don't actually know/remember even though it was just about a month or two ago. I just looked up the syntax for loops, functions, classes, variables, and started typing and fixing syntax errors as I went along.

Twig Date Parser Filter

2015-11-12T00:00:00+00:00

I've recently been working with joining Wufoo and DaPulse together happily in marriage and have made solid progress. However, one problem I encountered was the lack of consistency between Wufoo's POST data and API responses for their date fields. For example, I would get dates formatted as YYYYMMDD from the POST data received from their webhooks but I'd get YYYY-MM-DD whenever I sent an API request.

The problem I ran into with this was that Twig (and most likely PHP) could not create proper DateTime objects from the inconsistent data. Twig had to guess the date and I ended up getting August 20, 1970. Because a quick Google search didn't give me anything and I had to resolve this issue, I wrote a parse_date Twig filter to handle these types of situations.

Date: <p>{{ PostData | parse_date(["Ymd", "Y-m-d"]) | date("M d, Y") }}</p>

You may responsibly give it as many possible date formats you'd like to try and it'll return a DateTime object after it finds the first valid date; this DateTime object can now be used properly with the date filter. This filter uses DateTime::createFromFormat() to check which date format will work. This filter will also accept a single date format if you do not need to guess from an array of possible formats.

Wufoo and DaPulse

2015-11-07T00:00:00+00:00

At one of my jobs, we have recently moved from Asana to DaPulse for task management and collaboration. I'm not part of either's marketing team nor am I sponsored by either of them so I won't advocate for either or say one's better than the other. We also use Wufoo for forms and we used to use Zapier to automatically create entries in Asana and assign them to my coworkers and myself based on the entries. At the time of writing this, Zapier falls unbelievably short with their support of DaPulse to the point where it's actually quite embarrassing and they shouldn't even be offering it in the first place.

Somedays, you just just need Wufoo and DaPulse to work together, but the native integration either a) doesn't exist or b) doesn't do what you want.

- Zapier

Hah... Zapier doesn't do what I want.

I took it upon myself to write my own webhook that would actually be usable for my team. I started writing PhpPulse—a PHP wrapper for working with the DaPulse API—so I would be able to make a lot more than just a link between Wufoo and DaPulse. Now, the wrapper still needs a lot of work but creating boards, pulses, notes, and updating column values all work; that is exactly what I used to build a quick Silex project that will accept POST data from Wufoo and then create pulses with appropriate notes containing the Wufoo data. This project is far from scalable and could use a lot of thought in making it better, but for anyone else in the same situation that my team and I were in and uses PHP, this is a good starting point for you.

There will be more to come regarding PhpPulse as I finish writing support for the rest of the API and there'll also be more to come for PhpSoda. I have a smaller project planned for all of the wrappers I've started so I'll write about that once I've launched it.

Welcome Into My Life, Jekyll

2015-10-25T00:00:00+00:00

It's been an eternity since I launched my Jekyll based website (this one) but up until now, I hadn't done much with it nor had I done much with Jekyll. It wasn't until recently where at both of my jobs, I started using Jekyll a lot more and was able to experiment and discover some better practices. I'm no Jekyll expert but I finally feel comfortable enough with Jekyll and Liquid to work with it efficiently to get a product out. Better yet, I am comfortable enough to be able to assist on #jekyll; that's an IRC channel for you youngins who only know Slack.

I was finally able to dedicate a weekend to work on my website and well, here we are; this is it. There is still a lot more that I have planned for my personal website, but that will probably be built in the coming days. I'm not using any CSS frameworks other than Thoughtbot's Bourbon and my very own OnTheRocks—a flexbox based grid system built before they were cool and common. There is still a lot of Sass I need to rewrite, fix, or optimize and probably quirks on the website but I really hope none of them are embarrassingly bad.

Welcome into my life, Jekyll.

My New Series: BZFlag Plug-ins for Dummies

2015-10-25T00:00:00+00:00

Throughout my time with BZFlag, I have written a large amount of plug-ins. Nowadays, I have adopted the API as my child. By this, I mean that I have started to contribute a lot to the API and documenting it for others to use. I have also shaped certain parts of it to my liking mainly so it benefits my plug-ins.

The plug-in API was originally created by JeffM2501 with the release of BZFlag 2.0.0; such a long time ago, right? There have been many amazing plug-in authors but all of them have moved on to other projects; e.g. flying_popcorn, LouMan, JeffM2501, and sigonasr2. I've respected all of them very highly, especially flying_popcorn since he was the one who (patiently) taught me how to write plug-ins.

With BZFlag activity being how it is, active plug-in developers are dwindling in the community. So, I would like to change that by sharing my knowledge of the API and write about how to write your own plug-in. To do that, I'm going to start a "BZFlag Plug-ins for Dummies" series. I will be explaining things in a manner so even a nontechnical person would be able to understand it; if you're a more advanced programmer who doesn't appreciate things being written in layman's terms, either bare with me or learn on your own because you're not my target audience.

For now, I will not be posting this information to the BZFlag forums or the wiki. Don't worry, there isn't any juicy drama between me and the other developers and that's why I'm not posting it elsewhere; it's easier to format and design things on my blog than on the forums or the wiki.

In this series, I will be using Ubuntu but besides the initial configuration, the code will be identical and it won't matter what I use. Also, I'm going to make a few assumptions about you, the reader:

You know some basic C++
- I will not be teaching you how to write C++; there are several people on the Internet better suited to do that
- If you have experience with another C-style or OOP language, that may be enough
You can install things on your computer
- This is required so you can configure it to be a development environment
You have some basic knowledge regarding Git
- This isn't mandatory nor does it play a huge role, but I will not teach it for the same reason I'm not teaching C++

I will be writing this series on my spare time, so be patient if the intervals between my "chapters" aren't to your liking. Remember, BZFlag is an open source project meaning we're all volunteers that donate our time, effort, and resources so everyone can enjoy a great game; there have been certain individuals who fail to understand this concept, so I felt it necessary to put that friendly reminder.

Introducing PhpSoda

2015-06-10T00:00:00+00:00

I'm very proud to announce the birth of a new project and its first release! It's called PhpSoda and it's not for the type of soda that you drink (even though I love soda), it's actually an acronym for the Socrata Open Data API. What's Socrata? Well they're a pretty neat company that hosts a lot of open data for governments. They host open data for the US Federal Government and for local governments like the City of Santa Monica, where I work at the time of writing this.

At my job, we use C# for everything development and my coworker contributed the .NET library to the Socrata community because the library that existed before had room for some changes and refactoring. Similarly, Socrata has an official PHP library for working with the API but... It had plenty of shortcomings and it wasn't written in a very object oriented fashion. While I'm definitely not one to talk, I felt that it only contributed to the reputation of bad PHP code. I decided to write my own PHP library and send a pull request to have my library listed under the "Community Libraries" section of the Socrata developer website.

Socrata is mainly aimed at the public sector and I know PHP isn't too common in the public sector but for the PHP enthusiasts out there, I hope this library helps! I'm always open to suggestions and feedback, just submit an issue and I'll be glad to discuss things.

I have spent hours documenting my library so please check out the Wiki and install the package via Composer!

I'm ecstatic to see my library listed on their website! This has been the first library I've written and one of my first standalone open source projects not related to BZFlag or WordPress. I plan on extending my horizons a bit further with some more projects I have in mind that I will open source, so stay tuned... This is exciting!

From Underachiever to Uhm...

2015-03-13T02:10:00+00:00

A really long time ago I posted that I was an underachiever and sorry to disappoint but I still am. Well... Sorta. Maybe. Mostly.

Alright, so it's my third year of college and I'm still not entirely fond of it nor the concept of it but I've grown to slightly tolerate it now that I've taken some classes that I've actually liked. I am still pissed off with the administration and the politics that happen within my university but that's anywhere, I guess... Not much I can do about that. Regardless of me liking the class, I'm still an underachiever where I have not had one class where I go out of my way to actually complete a project or homework assignment or study for it. Not even my computer science classes. Really? Yes, really. I really do not mean to sound arrogant but my computer science classes are beyond boring, I haven't learned much from my professors with the exception of ARM. Heck, I have even had friends in higher level classes come to me for help and I've been able to help them. So computer science classes get the least amount of effort and the most amount of experimentation. By experimentation, I mean I try a lot of ideas that I come up with no matter how bad or good of a practice they are, so it has its perks.

I always open source my homework assignments and it seems that my classmates have "forked" my homework assignments to turn it in as their own... While that was not my intention, I won't cease to open source my homework simply because other people are turning it as their own. I know a few classmates do appreciate the examples and working examples.

Now, I'm not going to say I'm a complete underachiever, I do put a lot extra effort into projects that I have started and care deeply about such as BZiON or LeagueOverseer. I also do put a lot effort into the projects I have at work simply because I enjoy it.

I guess you could say I only put effort when it's something I enjoy. I guess I don't enjoy school. Oops...

From WordPress to Jekyll

2015-02-06T22:45:50+00:00

Well I never thought the day would come where I'd move away from WordPress for my personal website. I've been using WordPress since 2009 and it has changed a lot since I started using it. Don't get me wrong, I still love WordPress and I do plan on contributing to it, but I want to give Jekyll a try. The main thing that drew me to Jekyll is the use of markdown and YAML for everything and I definitely love both of those things; using this combination definitely beats writing a WordPress plugin to handle custom data. I will admit, making a theme for Jekyll is far simpler especially since I've started working with Symfony which uses Twig; Liquid is very similar to Twig so it's incredibily simple for me to get used to. Adding real time information to Jekyll is a pain since there is no server side processing; everything is static (no shit, sherlock). By using JavaScript and APIs, I can get by with having some dynamic content; although for the 1% of people who don't have JavaScript enabled, you just can't fully experience my awesome site.

I am going to really miss reading all of the password combinations, I just might create a dummy page just to continue reading them. I mean who wouldn't want to see admin:pussy69 in their failed login logs?

By moving to Jekyll, it has given me a great opportunity to clean up my website and finally organize things properly so this was the perfect moment. Not only will I be cleaning up all of my pages, I will also be deleting a lot of blog posts that I've written in the past that I'm just embarrassed about.

Since I just started using Jekyll here are some immediate pros and cons:

Pros

Much faster load times
Quicker and simpler theme development
No need for a database with a lot of different entries
Nothing to hack...

Cons

Lack of server side processing
- I am unable to have any dynamically generated content; I will be forced to create my own API and use other APIs to generate some dynamic content. On the bright side, I will be able to practice my JavaScript more

So far, I'm satisfied with Jekyll and I'm hoping I'll be able to continue using it and hacking on it by writing my own Jekyll plug-ins.

Also, there are a lot of shit designs out there for Jekyll websites. I do have to say, mine is pretty awesome in comparison.

allejo.io | interstellar space pirate extraordinaire

How and why I jailbroke my Kindle

Why am I jailbreaking my Kindle?

The Jailbreaking Process

The Prerequisites

Run the Jailbreak Exploit

Persisting the Jailbreak (aka "Installing the Hotfix")

Install KUAL and MRPI

Disable OTA Updates

Restoring the Store

Installing KOReader

Setting Up SSH

Screenshots

Add a Dictionary

Through KOReader's Top Menu

Manually via SFTP (or wired)

Exiting KOReader

Next free weekend's task: integrating calibre

Being Promoted to Customer at Stack Overflow

The Job Hunt

Things I'm Tired of Hearing

What am I up to now?

Joining Stack Overflow

Leaving the Public Sector

Interviewing at Stack Overflow

About the Interviews

What’s it like?

Wait, We Have Customers?

Describing a College Campus

Customers on a Campus

A Sharing Development Culture

But Law is Scary!

2019 Year-in-Review

Grad School?!

The Rest

Software Accomplishments

What's next?

The Unsolicited Job "Offer"

The Building of the New BZFlag.org

The Good and Bad of CSS

Collections + Searching

Datasets

JavaScript-less Syntax Highlighting

PageViews

Collection Management (Static + Dynamic PageViews)

Static PageViews

Development Web Server

Conclusion

The Importance of a Community Manager

Show Your OS Devs Some Love

Why I Built stakx

Static Site Generator (SSG) Comparisions

Looking Back

Is stakx for the masses?

Jekyll Heading Anchors without JavaScript

TL;DR

Usage

How it Works

Step 0

Step 1

Step 2

Step 3

Conclusion

One Year of jekyll-toc

BZFlag Plug-ins for Dummies: Chapter 9

Plug-in Specification

Registering Custom Flags

Implementing Custom Flags' Behavior

Step 1

Step 2

Destroyed by Server

World Weapon Management

Step 3

Step 4

Step 5

Step 6

Step 7

Final Plug-in

Conclusion

Recap of 2017