• Previous part (5)

I had finished programming the non-visual part of Team Struggles (a part of the encounter system that involves character traits and psychological dimensions against some performance thresholds) when I faced the fact that the game was loading too damn slow. I admit, I have been a bit overeager demanding more anime photo IDs from Midjourney, and they are completely unoptimized, but still, I figured that this project could load much faster. So I figured the following solutions:

• Lazy loading. Instead of loading encounter, biome, and photo ID images at once, just the image path is registered. Right before I need to draw a certain image, I check if it has been loaded, and if it hasn’t, I load it. That makes it so that the many images that won’t be seen in a particular testing session won’t need to be loaded at all. This change alone has sped up game loading significantly.
• Multithreading. This project didn’t feature any multithreading up to this point, as it is a static, 2D strategy game, but the process of loading the various parts (most of them from TOML files) could use some multithreading. My previous experience with this subject involved trying to develop a Dwarf Fortress-like simulation in Python, only to realize that Python isn’t suited for multiprocessing, nor remotely big simulations at all, due to its garbage-collected nature and a core that is locked to a single thread. However, Rust has mature crates that make multiprocessing relatively simple.

I asked GPT-4 to give me an overview of multiprocessing in the Rust programming language. It suggested a combination of the “rayon” and “crossbeam-channel” crates. The process works like this:

let (sender, ecs_receiver) = crossbeam_channel::unbounded();

You declare a sender and a receiver. The sender part will put on a queue the work done from a different thread, and the receiver will remain on the main thread to try to figure out what it can extract from the queue. However, those threads don’t need to disconnect: they are open channels. I assume that you could have a dedicated thread pumping out pathfinding-related calculations back to the main thread.

Spawning a thread is as easy as the following:

       std::thread::spawn(move || {

            load_ecs_threaded(sender);

        });

The “move” order, or whatever you would call it, is tricky. Any information at all that you are sending from the main thread changes its ownership, even if you clone it normally, so you need to use the “Arc” library to clone it in some special way. Not sure how expensive it is.

Anyway, “load_ecs_threaded(sender)” is in this case the function that will run in the spawned thread. The definition and contents are the following:

use crate::{

    gui::image_impl::ImageImpl,

    world::{create_world, ecs::ECS},

};

pub fn load_ecs_threaded(sender: crossbeam_channel::Sender<ECS<ImageImpl>>) {

    sender

        .send(create_world::<ImageImpl, ECS<ImageImpl>>())

        .unwrap();

}

That function merely sends through the sender the results of the “create_world” function, that registers all necessary components with “specs” Entity-Component System.

You won’t be able to check if the spawned threads have done anything unless you are running some sort of loop on the main thread. In this case I’m running the game with the 2D game dev “ggez” crate, which operates a simple, but well-working, game loop. From there, you need to rely on the “receiver” part of the channel to try to receive data:

        if let Ok(ecs) = self.ecs_receiver.try_recv() {

            match self.shared_resources.try_lock() {

                Ok(mut bound_shared_resources) => {

                    bound_shared_resources.set_ecs(ecs);

                    self.progress_text = Text::new(“Loaded Entity-Component System”.to_string());

                }

                Err(error) => return Err(GameError::CustomError(format!(“Couldn’t lock shared resources to set the world instance. Error: {}”,

                error))

                ),

            }

        }

Through the call “ecs_receiver.try_recv()” I will get either an Ok or an Error. An error may just be that the channel is empty because the remote function hasn’t finished working, so we just check Ok. In that case, the thread has finished doing its job. We gather the results (the “ecs” in this case) and store it into our shared_resources as I did previously.

That’s all. You need to be careful, though, because there are some structs that you can’t send through channels. For example, you can’t send the graphical context of “ggez”, meaning that you always need to load images in the main thread. You also can’t send the random number generator through, as it’s explicitly working on a single thread. But I haven’t found any issue sending my game structs.

Now that the game doesn’t seem to freeze on launch, I can focus on implementing the visual aspect of Team Struggles.

• Previous part (4)
• Next part (6)

A couple of entries ago I presented my first version of the encounter screen. As the team of explorers wanders around in the map, the stored encounters will get shuffled, and the first one whose condition gets triggered will present itself. Here’s the somewhat updated screen:

I was checking out the moddability of this game by changing most pictures to manga/anime aesthetics, and I realized that I liked it more this way. With a simple change of directory names, all names and pictures could get swapped to American ones. In any case, this screen presents what encounter has been triggered. The description gives a brief overview of the situation. The rest of the text informs that this encounter, at least the psychological part of it, will test each team member’s self-regulation (which is one of the psychological dimensions, the grouping of a few psychological criteria).

Yes, I know that there’s a lot of black space. Don’t know what to do about that.

Once you click the round button on the lower right, you are shown the results of the psychological test:

A brief text indicates the reason of this psychological test; in this introductory event/encounter to a narrative line called “The Verdant Assembly,” the characters test their self-regulation against the overwhelmingly lush and alien surroundings. For each character, the average value for that psychological dimension gets tested against a series of performance thresholds in the TOML files. The highest threshold they pass, they get that reward (or punishment). In game terms, an Encounter is associated with a series of Outcomes. Here’s how the outcomes for this encounter look like in the raw TOML file:

# Possible placeholders:

#

# {CHARACTER_NAME}

# {CHARACTER_FIRST_NAME}

[[outcomes]]

identifier = 1

outcome_type = “PsychologicalTest”

description = “Overwhelmed by the alien nature of this plant-based world.”

consequences_identifier = 1

[[outcomes]]

identifier = 2

outcome_type = “PsychologicalTest”

description = “{CHARACTER_FIRST_NAME} becomes fascinated by the plant-based entities, leading to increased motivation and a desire to learn from them.”

consequences_identifier = 2

They are self-explanatory. The most important part is that they link to another store of game entities, the Consequences. I intended to unify the concept of game consequences to a single block of game logic that could be applied to psychological tests and, in the future, to team struggles. The TOML file of related consequences is the following:

[[consequences]]

identifier = 1

illness_identifiers = []

injury_identifiers = []

mental_status_effect_identifiers = [1, 2]

character_trait_identifiers = [1]

add_features_identifiers = []

remove_features_identifiers = []

[[consequences]]

identifier = 2

illness_identifiers = []

injury_identifiers = []

mental_status_effect_identifiers = [3]

character_trait_identifiers = []

add_features_identifiers = []

remove_features_identifiers = []

It is quite inexpressive in its contents because it only links to other entities through their identifiers. However, the outcome of each psychological test and team struggle could have any of the following consequences (or all of them):

• The team member(s) involved receives one or many illnesses. Illnesses reduce the team member’s health every turn until they run out or are cured.
• Receives one or many injuries. Instant reduction of health, and the permanent ones even reduce max health.
• Receives one or many mental statuses (like Confused or Discouraged). They increase or reduce the value for associated psychological criteria.
• Receives one or many character traits (like Terrified of Octopi, or Botanist). These help or hinder during team struggles.
• The exploration zone the team is exploring either gains or loses features. For example, if some outcome enrages the natives, the exploration zone could gain the feature Enraged Natives, which would present more combat-oriented encounters in the future.

The consequences are already being applied in the code (which was some heavy amount of code, well-tested thanks to test-driven development), and once I get around to implementing team struggles, their consequences will work seamlessly with the code already written.

In the near future I’m going to focus on making sure that encounters can be blocked by other encounters or even their outcomes, if necessary. For example, if during a team struggle the team screws up bad enough to unleash something dangerous, that should cut off access to more positive branches of that same narrative.

A detail about Rust’s fastidious nature: this is a programming language built upon security and protection against the nastiest bugs from the C++ era. As far as I can tell, in Rust it’s impossible to corrupt some memory allocation that it wasn’t supposed to touch. That forces you to change your approach to programming in quite a few ways, but not because Rust is annoying for no reason, but because in other languages you were doing dangerous things. In my code, I was passing around a SharedGameResources entity that had access to “specs” Entity-Component System (that’s a whole thing; if you are interested, google it) as well as the stores of data loaded from TOML files. At one point I had to borrow that SharedGameResources entity both as immutable (just to read from the stores) as well as mutable (to write the results in the components). That’s impossible. Although it forced me to rewrite some basic architectural code, it illuminated the point that stores of game systems (like the “databases” of mental status effects or of character traits) are separate to the Entity-Component System, which handles a lot of mutation. In the end, Rust’s compiler steers you towards proper architecture, because you simply can’t run your program otherwise.

• Previous part (3)
• Next part (5)

As I was writing unit tests for a perilous, convoluted part of the game logic, which I wanted to lock in place as I moved forward, I realized that to test one relatively small part of the code, I would need to create both World, the main entity of the Entity-Component System “specs”, as well as Image, which is tied to the Context of the 2D game dev “ggez” crate. World is heavy by itself to fire up for a simple unit test, but Images themselves may not even be feasible, as they are glued to the graphical context (no graphics should run during unit tests), and they are tied to a single thread, while the unit tests run in all CPUs.

Therefore, I came to the dreaded conclusion: I needed to refactor their entire code into traits (interfaces). Traits are contracts that encapsulate a behavior without implementing anything. If you program to traits (interfaces) instead of to classes, you are working with future, potentially unimplemented structures whose details are irrelevant to you or the compiler, because they are only forced to fulfill a contract (the trait/interface). It’s like telling an animal to say something; a dog would bark, a cat would meow, but both have fulfilled the contract of “talking,” which is apparently all you cared about.

It just happens that traits in Rust involve generics, and generics in Rust are unholy. Due to Rust’s welcome but tough borrowing rules and lifetime whatevers, Refactoring any behavior to traits involves dealing with bizarre generic declarations, and worse yet, nearly incomprehensible lifetime signatures.

Behold the horror:

pub struct MainState<‘a, T: ImageBehavior + ‘static + std::marker::Send + std::marker::Sync + Clone, U: WorldBehavior<T>> {

    active_stage: Option<GameStage>,

    base_state: BaseState<‘a, T, U>,

    expedition_state: ExpeditionState<‘a, T, U>,

    encounter_state: EncounterState<‘a, T, U>,

    shared_game_logic: Arc<Mutex<SharedGameLogic>>,

}

That’s the definition of MainState, the head honcho of the state machine that figures out which other stage needs to update, or draw on the screen. It declares that it’s somehow involved, to start, with an ImageBehavior contract. Every image throughout the program, except in the launcher, is now unaware of what type of structure it’s actually dealing with, except that it fulfills the contract of being static (I assume images are fixed in memory or something), they Send and Sync for multithreading, and can be Cloned. That’s the hardest one. Then we have WorldBehavior, which abstracts away the entirety of the “specs” Entity-Component System into a wrapped class. The resulting contract for WorldBehavior, if I may say so myself, is a thing of beauty:

pub trait WorldBehavior<T: ImageBehavior + std::marker::Sync + std::marker::Send + Clone> {

    fn new(world: World) -> Self;

    fn join_coordinates_and_tile_biomes(&self) -> Vec<((i32, i32), TileBiome)>;

    fn retrieve_player_coordinates(&self) -> Option<(i32, i32)>;

    fn retrieve_biome_at_player_position(&self) -> Option<Biome>;

    fn retrieve_unique_character_traits_of_team_members(&self)

        -> HashSet<CharacterTraitIdentifier>;

    fn count_team_members(&self) -> u32;

    fn calculate_average_mental_strain_of_team(&self) -> f32;

    fn calculate_average_health_of_team(&self) -> f32;

    fn set_player_position(&mut self, x: i32, y: i32);

    fn retrieve_player_entity(&self) -> Entity;

    fn retrieve_name_of_entity(&self, entity: Entity) -> Name;

    fn retrieve_psychological_profile_of_entity(&self, entity: Entity) -> PsychologicalProfile;

    fn retrieve_health_of_entity(&self, entity: Entity) -> CharacterHealth;

    fn retrieve_team_members(&self) -> Vec<Entity>;

    fn retrieve_team_members_except_player(&self) -> Vec<Entity>;

    fn retrieve_photo_id_of_entity(&self, entity: Entity) -> PhotoId<T>;

    fn move_direction(&mut self, direction: Direction);

    fn create_entity(&mut self) -> EntityBuilder<‘_>;

}

With that contract in place, there’s no more need to deal with “specs” way of working. You want to retrieve the player entity? Call “retrieve_player_entity”. Do you want a calculation of the average mental strain of the entire team? Call “calculate_average_mental_strain_of_team”. Of course, the contract can be developed further as more information or calculations need to be gathered.

I’m at ease now that I have managed to refactor those two unit test blockers into behaviors, but it took hours, and if it weren’t for the indefatigable help of GPT-4, I wouldn’t have been able to do it. But thankfully there shouldn’t be any major obstacles to unit test every part of the code now, which should speed up development significantly.

A boring entry compared with the three previous ones, perhaps, but programming is a fight against entropy: the further you build your system, the harder it becomes to change. You have to stop every few days (if not once a day) to make sure that some part of the code isn’t rotting already.