How Does It Work: Asperta

[background-block=#00367c][center]
[img]https://raw.githubusercontent.com/Europeia/images/refs/heads/main/ebc-headers/ebcspecialreport.png[/img]
.
[/center][/background-block][background-block=#ff3919][center][color=#ff3919].[/color]
[font=Playfair Display][size=190][url=page=dispatch/id=1552024][color=#fff]Start Here[/color][/url] [color=#00367c]/[/color] [url=page=dispatch/id=426900][color=#fff]World Assembly[/color][/url] [color=#00367c]/[/color] [url=https://www.nationstates.net/page=dispatch/id=349445][color=#fff]Citizenship[/color][/url] [color=#00367c]/[/color] [url=page=dispatch/id=353881][color=#fff]Government[/color][/url][/size][/font]
[color=#ff3919].[/color][/center][/background-block]
[box]
[center][font=Playfair Display][size=240][b]How Does It Work: Asperta[/b][/size][/font][/center]
[center][font=Playfair Display][size=160][i]Written By [nation]upc[/nation]
Edited By [nation]vorhollah[/nation][/i][/size][/font][/center]
[hr]

[font=Playfair Display][size=160]Across the history of NationStates, there are countless examples of players creating tools to programmatically assist in various interactions with the game. These tools range from simple [url=https://github.com/nsupc/login-py][color=#ff3919][b]login scripts[/b][/color][/url] that run every so often to prevent nations from Ceasing to Exist (CTEing), to [url=https://github.com/esfalsa/srsglass][color=#ff3919][b]command-line utilities[/b][/color][/url] for parsing NationStates daily dump archives into spreadsheets, usually used for R/D purposes. In the 'How Does It Work' series, I hope to tell the stories of some of these tools -- how they work, why they work this way, and to hopefully explain some of the cool technical details in a way that is digestible to people who don't code themselves. In this first edition of the series, I will tell the story of Asperta, Europeia's recruitment bot.[/size][/font]

[font=Playfair Display][size=160]Prior to the creation of [nation]Asperta[/nation], which is named after one of Europeia's most prolific early recruiters, we used a web based recruitment tool created by [nation]r3naissancer[/nation]. This tool served the region well for many years, but proved difficult to maintain after r3n's retirement, and it was completely shut down along with the rest of his legacy tech in late 2022. This left Europeia in a very awkward position, as our recruiters were forced to do their job through the world activity feed for the first time in probably over a decade. Around this time, then-Minister of the Interior Vor reached out to me about the possibility of developing a replacement tool, and I decided to adopt Discord as the platform for the replacement, as I already had experience in writing Discord bots, and because the majority of our recruiters already frequented the Europeian Discord server.[/size][/font]

[font=Playfair Display][size=160]Asperta is designed around a queue of nations (this is a bit of an oversimplification, but we will get back to this later). For each nation in the queue, the bot retains three pieces of information: the name of the nation, the region it founded in, and what time it was founded at. Most of the bot's functions revolve around putting nations in the queue and then subsequently taking them out.[/size][/font]

[font=Playfair Display][size=180][b]Adding Nations to the Queue[/b][/size][/font]

[font=Playfair Display][size=160]Inside the bot is a method called update_queue, which, surprisingly, tries to add newly founded nations to the queue. Every fifteen seconds, this function makes a request to the [url=https://www.nationstates.net/pages/api.html][color=#ff3919][b]NationStates API[/b][/color][/url] (fun fact: it uses a special API endpoint -- [url=https://www.nationstates.net/cgi-bin/api.cgi?q=newnationdetails][color=#ff3919][b]newnationdetails[/b][/color][/url] -- that was [url=https://forum.nationstates.net/viewtopic.php?p=40490748&sid=b7de0adc4ea23eaff649a78c2a825b30#p40490748][color=#ff3919][b]requested[/b][/color][/url] by [nation]Decacon[/nation] specifically for this project!), and if new nations have been founded since the last time the function has run, they are added to the queue. When a nation is added to the queue, it is done in reverse founding order, such that the newest nations are always at the top. This is because we always want to prioritize recruiting the most recently founded nations -- these nations will have received fewer telegrams, and are thus more likely to receive our telegram (which is not guaranteed, fun fact) and less likely to have already made a decision as to where they would like to move, if anywhere. Not every nation makes the cut, though. We don't want to send telegrams to nations that founded in Europeia or Concord, for example, so we added the ability for regions using the bot to ignore nations that found in specific regions. We also added a basic filter using a regular expression, or regex, which looks like this: [/size][/font][font=Roboto Mono][size=170]r'^\d+|\d+$'[/size][/font][font=Playfair Display][size=160], that checks if a nation's name starts or ends with a number (e.g. '100 walruses' or 'UPC is not Fast 1'). This does not block every puppet series, of course, but is pretty effective at doing so while minimizing the number of false positives -- legitimate nations that are marked as puppets and thus excluded from recruitment.[/size][/font]

[font=Playfair Display][size=180][b]Removing Nations from the Queue[/b][/size][/font]

[font=Playfair Display][size=160]Nations can be removed from the queue in two ways. The preferred way, of course, is for a recruiter to hit the 'recruit' button, which will take the eight newest nations from the top the queue and return them to the user to telegram. The other way that nations are removed is by being purged. Previous research performed by the Ministry of Outreach has determined that the first hour after a nation is founded is the best time to recruit it -- telegrams sent after that rarely have an effect. So each time the bot updates the queue to add newly founded nations, it also checks for remaining nations founded over an hour ago, which are promptly discarded.[/size][/font]

[font=Playfair Display][size=180][b]Recruitment for Multiple Regions[/b][/size][/font]

[font=Playfair Display][size=160]One of the most recent features of Asperta is its [url=https://forums.europeians.com/index.php?threads/shifting-sands-an-updated-outlook-on-nationstates-recruitment-and-asperta.10066560/][color=#ff3919][b]ability to serve multiple regions simultaneously[/b][/color][/url]. This is where the complications in the queue that I alluded to earlier start to appear. If we only used one list of nations, then only one region that was using the bot would have a chance to recruit a given nation, which made sense when only Europeia was using the bot, but now that it is in use in Europeia, The League, Concord, and 10000 Islands, that is a bit less practical. So instead of being built around a single queue, the bot is actually built around a group of queues, one for each region that uses it to recruit. When a new nation is added to this [/size][/font][font=Roboto Mono][size=170]QueueList[/size][/font][font=Playfair Display][size=160], a copy of it is added to each individual region's queue, unless the nation spawned in a region that the recruiting region chose to ignore.[/size][/font]

[font=Playfair Display][size=180][b]Reporting[/b][/size][/font]

[font=Playfair Display][size=160]The last major piece of the bot that I want to talk about today is the reporting feature. Every time a user clicks 'recruit,' the bot stores a record in a SQL database containing the user, the time, and the number of nations in the recently sent batch. This allows us to create recruitment reports for very specific periods of time -- the bot's reporting form allows for up to the second specificity, though most reports stick to the default, which is midnight - midnight UTC. Within this date range, the bot adds up all of the recruitment batches sent by each user, and then returns a list of everyone who recruited, ordered by the total number of telegrams they sent. Here is this week's report, as an example:[/size][/font]

[quote=Recruitment Report- Sept 13-20 2024;0][font=Playfair Display][size=160][nation]sincluda[/nation]: 2004
[nation]weeklingz_federation[/nation]: 1012
[nation]upc[/nation]: 858
[nation]grea_kriopia[/nation]: 675
[nation]maowi[/nation]: 385
[nation]lloenflys[/nation]: 325
[nation]istillian[/nation]: 296
[nation]westinor[/nation]: 218
[nation]mancheseva_city[/nation]: 191
[nation]aleutria[/nation]: 132
[nation]not_to_fret[/nation]: 81
[nation]darcness[/nation]: 68
[nation]ambrella[/nation]: 53
[nation]empire_of_caldrasa[/nation]: 47
[nation]vorhollah[/nation]: 33
[nation]kasaria[/nation]: 31
[nation]industhan[/nation]: 27
[nation]the_islamic_country_of_honour_eia[/nation]: 17
[nation]great_viltrum[/nation]: 8
[nation]12_aaa_batteries[/nation]: 8
[nation]pland_adanna[/nation]: 8
[nation]jaydee_ii[/nation]: 8
[nation]le_libertia[/nation]: 7
[nation]phdre[/nation]: 2[/size][/font][/quote]

[font=Playfair Display][size=160]This has been a very fun piece for me to write, and I hope that it is just as interesting to read. If you have any questions about something I've written here, or about another of Asperta's features, please feel free to ask about it on the [url=https://forums.europeians.com/index.php?threads/how-does-it-work-asperta.10067310/][color=#ff3919][b]forum version of this article[/b][/color][/url], and otherwise, I will see you in our next installment of How Does It Work![/size][/font]
[/box]
[background-block=#00367c]
.
[align=center][font=Playfair Display][size=170][url=http://europeians.com/forum/index.php][color=#fff]Forum[/color][/url] / [url=page=display_region_rmb/region=europeia][color=#fff]RMB[/color][/url] / [url=https://discord.gg/nYAwZ7f][color=#fff]Discord[/color][/url][/font][/size][/align]
.
[/background-block]