DEV Community: amu

Script Files as Configs (Instead of JSON and YAML)

amu — Sat, 23 Mar 2024 05:01:08 +0000

This is a small post to share a general idea that might be helpful in scenarios involving a lot of config files.

The idea is for the host the program to not read text configs via file operations. Instead, host program runs script files and uses their std outputs. Both of the approaches result in a string that is further processed in the host program. However, there are many merits to the latter approach that is simply not available in a text file.

Why would this be helpful?

At the end of the day, the host program only wants a string for configs, whether it reads the text file or runs the script process.
However, using a script as config will allow for more operations and freedom in defining configs.

The data that is treated as a series of characters in the text config are variables in the script configs. Those variables are processed, and eventually serialized and printed to stdout. Then the stdout is used by the host program. You can use any feature that the scripting language provides before presenting the serialized config to the host.

This approach doesn't clash with the idea of separation of code and data. A lot of times, being mindful of the data in the code is a helpful policy for decreasing hard-coding. However, in the use-case of configs, we are treating script files as "data showcased with finesse" rather than "code".

Examples

Here are some scenarios as examples:

OS specific configs:
- Text config: Add multiple config files, have the host program detect the os settings and access the right config file
- Script config: Use the scripting language's OS library to automatically present the right config
Variation/presets of configs:
- Text config: Add multiple config files
- Script config: Host uses the process command line arguments when spawning it in order to pass any variables for the config.
Config content might not be present and need to be fetched:
- Text config: The text config doesn't exist. Host program needs to fetch it from disk/network and parse that data. Text config doesn't work.
- Script config: Script can handle the fetching of the config instead of host. It can use the language's networking libraries.
Config content has errors or is corrupted:
- Text config: Text config doesn't recognize it. Host will have to handle it completely.
- Script config: Script can neutralize and defuse the errors to some extent instead of leaving it all to the host program.

Config of configs

Of course script config can use it's own text configs too, if you find that kind of design to be helpful for your application:

...

I originally got the idea when I was playing with Neovim, in which you set your personalized configs in a Lua file rather than a text-based config file extension such as JSON.

Anyways, I think this is a cool idea. Thought I'd share it here.

Associated Class Members Introduce "Dimensions" to Classes

amu — Sun, 10 Mar 2024 03:47:35 +0000

Usually, in the more useful object oriented tips the focus is more on improving the inheritance relations. Which is wonderful; it is nice to not see long inheritance chains. Even better, it is nice to see composition more than inheritance.

But there is another kind of chain that is caused just by using an object within the class regardless of composition and inheritance.

If a class uses another object in any form of association-esk relation, it introduces new "dimensions" for it. You could say in a very simple sense, dimension is observed through the number of dots you enter when accessing a method within the class: this.object_a.object_b.object_c.hello().
You want the number of dots to be "enough" so that the class is properly "populated" and/or "bloated."

Too large of a dot count might be the sign of a class doing something that is too low-level given its abstraction layer.

Consider a very dimensional class on one side of the spectrum, with the other side being a flat class. The flattest class contains only "plain old data" types. This means there might be custom objects within our class, but they don't have functionality; they're merely a collection of data and perform primitive operations on them.

It is useful to take a second to reconsider whether a new dimension would be helpful before starting the implementation. It greatly contributes to reducing overengineering. The principle/idea is to usually prefer being more flat unless it is obvious that introducing dimension helps more. E.g. when a collection of members and methods are gravitating towards a certain behavior that can become a class on its own.

Using this policy, the dimensions are grown out of necessity, not out of our imagination of arbitrary necessities when they don't exist.

Overengineering is born because the abstractions are larger than the requirements of the current code. Moreover, in an overengineered code, you have to fit the feature into the structure. But when the class is flatter, more free-form, you can just add a piece of code and then carve out abstractions based on that, if needed.

This stands in any granularity level:

Variable: Does this value really need to be saved in a variable and occupy memory?
Method: Do these few lines of code really need to be a method?
Class: Does this collection of variables and methods really need to be a class on its own? Or is it okay enough to be in the class that they are currently residing in?

Having more dimension increases complexity. This statement is against the traditional "clean code" that generally encourages more classes and methods. Complexity isn't a "bad" thing. Complexity is a property that naturally exists, like the BMI level of human body. We just need to make sure it has a "reasonable" amount.

Tackling Temporal Dependency in Classes

amu — Wed, 06 Mar 2024 12:29:14 +0000

My definition of Temporal Dependency is when a part of the system/ecosystem/class needs to be aware about the order/timing of other operations.

It exists on every category of systems in which subsystems communicate with each other. However, in this article I want to mainly focus on a very common setting: Object oriented classes. It is absolutely crazy how underrated this topic is given the mental load that it causes.

In an object-oriented class, there isn't a clear sense of in what order are the methods allowed to be executed. Except for the constructor and deconstructor/destructor, other methods do not have any constraints in the language level to be called in any specific order.

The explained problem might not seem a significant in a small class but if you have a large number of classes that each have a large number of methods, it would be hard to control the temporal dependency. Both when you want to learn and edit a class, and also when you want to use a class's method elsewhere.

Of course there are many ways to tackle this issue. I think they fall into one of these 3 levels:

Code Level
Language Level
Paradigm Level

Code level

Essentially, you can write code to handle the issue:

One way to tackle it is using a combination of assertions and enums/flags that contain internal state of the class. This means that for the classes that need extra care, you can define enum indicating the operational state of the class and for certain methods assert the wrong states.

enum class_state { s1, s2, s3 }

class a
{
    class_state state;

    void some_method()
    {
        if (state != class_state::s1) 
            return;
    }

    void some_other_method()
    {
        if (state != class_state::s2) 
            return;
    }

    void some_other_method_too()
    {
        state = class_state::s3;
    }

};

Another similar way would be to have represent the state of the class by bits. For example 0x00000000 is the class state that supports 8 different conditions. If the state value is 0x00000101, it means that the conditions 1 and 3 are met. Then for a method, we can check that the conditions are met via bitwise & operation:

void some_method()
{
    // changing the current state
    state = state | 0x00100001;
}
void some_other_method()
{
    // using the current state
    if (state & 0x00011101 != 0x00011101)
        return;
}

This indicates that the method needs the condition of 0x00011101 to be met in order for it to be run.

Of course there are countless other ways that you can come up with.

Language Level

Using language's built-in features.

For example,

Language's class constructor is ensured to be called as the first method when an object is created.
Deconstructor/destructor is ensured to be called as the last method before the death of an object.

Of course, you can choose not to use them. You can write your own "Initialize" and "Deinitialize" or kill methods. The only difference will be that the programmer needs to logically make sure to call them directly after the object creation and before the death, whereas constructor/deconstrutor is called automatically in the language's runtime.

This level's features are not in the programmers hands usually. Programmers can only use what the languages offer.

Paradigm Level

This concerns the way you approach architecting the code. When you write procedural code, you naturally count in the temporal dependency as opposed to when you write object oriented code.

To deal with the issue of temporal dependency, there can be middle grounds between paradigms. You can use object-oriented but mix in some procedural goodness; write classes that are traditionally "dirtier," with less number of methods and care less about "single responsibility," but instead have more procedural codes in those methods. That can be a helpful way to solve this issue to a degree. [The notion of clean and dirty is too relative, fragile, and context-dependent. It's not worth religiously obsessing over. But that's for another post.]

What's the "best" way?

I think the "best" way to tackle the temporal dependency is a combination of ideas on the 3 levels, given what makes sense for you and your project. The paradigm level decisions provide higher chunk of the value because they affect the way you approach writing code more. And of course, there is no singular best way.

Contexts are important

It's helpful to mention two general points:
1) Of course, this topic isn't always a problem. It depends on the context of the code itself and the development environment. The deadline, the team size, the code size, etc.
2) Temporal dependency isn't a "bad" thing. It's just an attribute that naturally exists when you have multiple instances entities that communicate with each each other. My main point is that if the temporal dependency is making the flow too hard to understand, then it might have room for being stated more clearly.

Subproblems in Software Design (aka the power of abstracting the problems)

amu — Sun, 03 Mar 2024 14:58:57 +0000

We study common realms of algorithms and data structures in order to use them in a more concrete way when solving problems (or to pass technical interviews.) For example, we study dynamic programming, graphs, sorting, etc.

And there are common subproblems that usually fit certain realm of algorithms. By which I mean if you zoom out of a problem and dissect it in a more abstract way, what types of algorithms does the context of your problem fit into? Common subproblems are not algorithms per se, they are contexts in which you can pick some algorithms to use for.

For example, a fairly easy-to-digest example is a social network
application that contains users that follow each other. If you have studied graph algorithms and data structures, you can map them to this problem's setting. Graphs are abstract and applicable to many different problem domains. For example they are also used in map and routing applications too. Whether it be for computer networks, or for actual real-life transit systems.

This post aims to talk about the merit of thinking abstractly in the software design and architecture level, and provide examples on how they can be helpful. I hope to encourage you to think more about abstractions. The term abstract here is used as opposed to "concrete." Something that is more abstract, is less domain-dependent and/or application-dependent.

For starters, if you have experience of working with design patterns, then you have already done it! Design patterns give you some boilerplate solutions to common design subproblems, regardless of the environment.

Here is an example: Let's say you have an entity that wants to communicate with another entity. A common design pattern that can solve this problem is the "Client-Server" design pattern. It's one of the most fundamental patterns used in creation of computer networks and the whole internet.

However, you may think that it is used only in the web context. But it's not just used in the web. Two other examples for its use-case are in LSPs (Language Server Protocol) and the Godot game engine. Let me briefly explain their concepts:

LSP is the tool that runs the autocomplete in your modern code editor. The client is your editor and the server is the LSP. Client sends the code text to the server, and the server returns auto-complete suggestions or possible syntax errors.
Godot is a very cool game engine in which many sub-parts of the engine communicate with the engine through a client-server manner. In this context, Godot is the client and it uses 2d and 3d physics servers, a sound server, etc. E.g. the sound server "serves" sounds for the core engine.

You can see the domains of internet, code editors, and game engines are vastly different in the domain of computers.

However, through abstracting the problem we can boil the problem down to this fundamental subproblem: I need to provide connection between two entities.

The stated sentence is okay, but I think it's not thorough enough based on those 3 examples. Those 3 examples have something more special to them: the fact that the two entities that need to be connected aren't necessarily in the same program:

In the internet, clients and servers are literally on different machines.
In LSPs, each programming language has its own LSP server and then we have different code editors that use LSPs such as Neovim, Visual Stuido, IntelliJs. Each of these things are developed by a different companies with different languages.
In a game engine, the constructing systems might be different processes of different languages. For example the physics engine might be a C library, the main engine core might be in C++, and the runtime scripting might be for Lua.

So, the specific and tuned subproblem that we are wanting to design for is this: I need to provide connection between to entities that aren't necessarily residing in the same environment.

Stating my core problem more accurately helped me to filter out some possible solutions that doesn't fit the exact criteria. I didn't know that detail of being in the different environment in the beginning. How I realized that was by revisiting the concrete problem again in order to extract the abstract idea more clearly.

Is the server-client idea the only solution for that problem? The answer is no. Here is an alternative solution: Server-client offers direct connection between the two entities. What if instead, we make a third entity that holds the data to be used between the two entities? Essentially a data container entity that can be a file, a database, a 3rd-party server, a process mutex, based on the domain of our application.

I argue that it even works on the paper for designing internet too. But it would be really bad and inefficient and inconvenient. It would mean that instead of my PC asking a server for the website content, I would submit my request on another 3rd-party server, and then the server that holds the website recognizes that request and puts the content on the 3rd-party server. And then my pc recognizes that there is the content there. This means that the trip counts are increased to more than 50% for each packet compared to the client-server model. This solution sucks, but it is still a solution.

Funnily enough, my latter solution is actually feasible if I change my initial question: let's say that I want my client to not always contact the server for acquiring repetitive information, so that the server load is reduced for unnecessary connections. Aka the concept of Cache in networks. With a few tweaks in details, the solution of a 3rd party server containing a cache table fits this problem really nicely. But it didn't fit the other question.

The fun point of software design is that upon hearing the problem statement, we can design many different solutions, and sometimes you can't prove one is better than the other. Algorithms are less free in this sense because a lot of times you have calculatable time and space values and limitations. An algorithm with the time order of O(logn), is just better than an algorithm with the order of O(n^2). But for design, it's less provable. There are measurement systems of course, but in design is more free by nature. (Also, just look at the JS Node packages dependency trees... It's clear that we don't care...)

In software design (and also algorithms), you can sample any realm of computers and apply it to another realm. Because the core skill that you use is the skill of abstracting problems and the solutions. You can change the skin, the scale, the programming language, etc. But the core is the same.

Heck, even the idea of orchestration tools such as Kubernetes come from the music orchestras. If you think about it, it is a really liberating perk that just by becoming a better analyzer of anything that you face around you, you can literally turn it to a possible design idea for a computer system.

I think the first time that I heard of this way of thinking was from a professor in the first week of college (eventually I grew to dislike his attitude, but initially liked them). He was talking about how computer scientists got inspired by birds, bees, ants, and fishes and created the swarm intelligence algorithms to simulate collective decision making behavior.

What I have observed is that many times, the core idea of the issue that I'm facing is nothing new. There are "common subproblems" that analyzing them can help improve solutions in other domains. So although my area of work is in games, it's still helpful and fun to study about other fields. Even fields that aren't about computers.

I think it would be fun to write more about some common subproblems in software design. Maybe I'll do that. For now, I hope this post is helpful to someone out there!

[BONUS PARAGRAPH] On other fields of science, art, literature, and philosophy, this approach is also common. Of the works that I'm a bit familiar with, Jacques Derrida's theory is exactly aligned with what I proposed here. He proposed the idea of "Deconstruction" in the subject of human languages. He argued that the meanings that are conveyed through language are deferred and context-dependent. They have ambiguities and contradictions. Derrida proposed that to properly analyze human language and the meaning conveyed through it, a nicer way would be break down the meaning into its constructing elements.
Computer languages, on the other hand, are context-free. They aren't ambiguous. The thing that makes the programs unpredictable is the way humans write the code using the languages, not the languages themself. The codes are complex because the writer of them did it in a complex way. (Then the Chat Jippities learned from those complex codes and kept rewriting them.)

Ideas for making more informative names

amu — Sat, 02 Mar 2024 14:22:27 +0000

Something that didn't catch my eyes and I just accepted the mental load that it always consumes was naming conventions. During the past few months I've been thinking about that. There are systems and conventions per language and per team, but I never questioned them deeply.

Here are some ideas that I've been testing on some projects and they are helping me. (Note that a lot of the ideas really apply on larger codebases and are probably not useful on a small codebase.)

1. PascalCase and camelCase are inconvenient for brain to parse

Consider these two ways of naming the variable:

AutomateAsync
automate_async

I find the latter much more clean for 2 reasons:

1) It might not seem much, but the spacing that is created by underline helps with readability. Especially, it adds up in a large file. If your codebase naming convention is PascalCase, when your brain wants to parse AutomateAsync it reads the name letter by letter and splits it via detecting capital letters. So it has to check at least 26 possibilities for each letter of the word. But with the underline, it's literally O(1). It's fundamentally less complex. Of course if you are familiar with the code, you might have no problems because you the longer names read as a single unit to you. But if the code base is huge and is developed by multiple people, or you have developed the code but haven't touched it for a few months, you need to focus on the name of variables more when reading the currently unfamiliar part to understand how it works.

2) Moreover, a PascalCased name, by nature, makes your brain slow down its crazy cache-based skimming functionality: while reading, your brain speeds up the word parsing process by focusing more on the begining and the end of the wrod. That's why you might have not picked up the tyops in the previous sentence. And the typo in the word "tyops" in the last sentence. In essence, your brain uses its word caching ability as opposed to processing every single word repeatedly that reside in its ram/disk. That is why you can read faster as you read more books. In the case of reading code, when your brain is aware that the codebase names are PascalCasely typed, it can't rely on that optimization as much, because it knows that is going to miss the middle of the word, where other words are formed.

2. Names can provide additional context by being longer

Names for files, classes, functions, etc can save a lot of time if they provide more context on their own. Again, this is more helpful in a larger code base and is overkill if the project is on a smaller scale.

My basic idea here is that using a separator and adding contexts to names will be helpful in many different use cases.

Here are some examples in different contexts and sizes:

2.1. For Naming Files [+ Directory Trees]

Without needing any context on the project, consider renaming a file called "effects.hpp" into "effects_manager.hpp". And in the same codebase rename the file "sound_played.hpp" into "sound_played_event.hpp". In this example, as you might have guessed, these files do something to sounds. The additional context provided in the names helped with indicating the granularity of responsibilities in the C++ header files. E.g. I expect that if I open the event header, I will see less things happening than when I open the manager event.

Of course, this isn't the first and only resort for providing context on the file level. In fact, providing helpful context by having a good folder structure pays off a lot.

Here's an example file tree from a part of the Godot game engine source code.

servers/
    |__> audio/
            |__> effects/
                |__> audio_effect_amplify.cpp
                |__> audio_effect_amplify.h
                |__> audio_effect_capture.cpp
                |__> audio_effect_capture.h
                |__> audio_effect_chorus.cpp
                |__> audio_effect_chorus.h
                |__> audio_effect_delay.cpp
                |__> audio_effect_delay.h
            |__> audio_driver_dummy.cpp
            |__> audio_driver_dummy.h
            |__> audio_effect.cpp
            |__> audio_effect.h
            |__> audio_filter_sw.cpp
            |__> audio_filter_sw.h
            |__> audio_rb_resampler.cpp
            |__> audio_rb_resampler.h
            |__> audio_stream.cpp
            |__> audio_stream.h
    |__> camera/
            |__> camera_feed.cpp
            |__> camera_feed.h

You can see how the directory names provide context, hence the path of a file provides context, and the file names on their own provide context, because when you work on code editor it's not nice to always look at the path of each file.

Here's an absolute nightmare example file tree, from the newly open-sourced Valve's audio engine called Steam Audio:

(Abbriviated list)
|__> src
    |__> core
        |__> binaural_effect.cpp
        |__> binaural_effect.h
        |__> math_functions.cpp
        |__> math_functions.h
        |__> matrix.h
        |__> memory_allocator.cpp
        |__> memory_allocator.h
        |__> mesh.cpp
        |__> mesh.fbs
        |__> mesh.h
        |__> profiler.cpp
        |__> profiler.h
        |__> propagation_medium.h
        |__> quaternion.h
        |__> reverb.fbs
        |__> reverb_effect.cpp
        |__> reverb_effect.h
        |__> scene.cpp
        |__> scene.fbs
        |__> scene.h
        |__> scene_factory.cpp
        |__> scene_factory.h
        |__> serialized_object.cpp
        |__> serialized_object.h
        |__> sh.cpp
        |__> sh.h
        |__> speaker_layout.cpp
        |__> speaker_layout.h
        |__> sphere.fbs
        |__> sphere.h
        |__> sse_float4.h
        |__> stack.h
        |__> thread_pool.cpp
        |__> thread_pool.h
        |__> triple_buffer.h
        |__> types.h
        |__> util.h
        |__> vector.fbs
        |__> vector.h
        |__> window_function.cpp
        |__> window_function.h

Upon looking at the files, I don't get why reverb effect code is near the thread pool or a 3D model file for a sphere. What does even sh.cpp mean? I may find out that the code is be phenomenally written when I open the code files and read the code. But the file naming and structure is just not good in the sense that it is not welcoming to a new maintainer. Bare in mind that you in the future can also feel like a new maintainer sometimes, even if you are the original author of the code.

This is generally a good question: Does the it make sense when you put yourself in the shoes of a person who is reading your code for the first time?

2.2. For Naming Functions

Here are some examples:

1) For some functions that I know are for debug or are temporary, I like to put that in the name to make sure I don't use it more than they should be used. For example, sometimes a temp method exposes too much of the structure.
For example:

void calculate_mass__tmp();
void serialize_file__debug();

Sometimes I get so annoyed that I have to write a really dirty function that I add that fact to the name too. So that whenever I call that function I get reminded that it needs to be cleaned. Eventually.

void send_request__TOO_DIRTY();

3. Naming in Reverse can Help Readability

Let's start by mentioning some examples:

You have a class for your game called player. The name "player" by itself is too vague for me when there are a lot of classes hanging around (as I talked about in previous ideas.) So I can add some context to the name. I can use "player_entity." This idea is about using "entity_player" instead. The reason is when you have a bunch of entities, it makes it easier to digest. As the following:

entity__player
entity__car
entity__ship
entity__bird

And maybe some components:

entity__player
entity__car
entity__ship
entity__bird
component__collider2d
component__collider3d
component__transform
component__rigidbody2d
component__rigidbody3d

Another example: you have a state machine and you have functions to handle each state:

enum states { PLAY, PAUSE, STOP }
on_state__PLAY()
on_state__PAUSE()
on_state__STOP()

For variables specifically, it doesn't usually seem that useful to me. Unless there are many variables with similarly formatted names. I generally don't like it because usually, when I'm caring about a variable, I'm most likely dealing with the code within the function contents and I'm willing to spend energy to learn what it does. But when I'm calling/using a function, I may not care about what happens inside it and I just want to pass inputs and receive outputs. In other words when I'm using a function the stakes is higher. When I'm writing something inside a function, the stakes are lower relative to calling.

As a general idea I think it is nice to be:

Extra considerate about the interface [things that are exposed]
Considerate enough about the non-interface [things that aren't exposed]

But here's an example for a bunch of variables, in a shop system of a game:

queries_max
transactions_max
users_count
queries_count
transactions_count

I can flip the context in variable names and bring it first so that the variables are sorted by context. So users_count will be count_users (kinda like count_of_users with an omitted "of".)

Now they are like this:

max_queries
max_transactions
count_users
count_queries
count_transactions

These ideas will change, 100%

These were my recent ideas I wanted to talk about in this post. I am sure they will change for me. Maybe even as soon as next week.

However, the mean concepts that I am sure about are this:

The way at least I name things, can be improved.
Language naming conventions are opinions that can be broken if you want to.

Anyways, I hope this gave you some ideas. Maybe ideas that you count as really bad and things to avoid. Which is okay with me. That's why it's fun.

Why I decided to get bad grades in college

amu — Mon, 29 Jan 2024 12:27:01 +0000

I had a hard time in college. The truth is that there weren't many courses that I didn't like the concepts of. But I really resented the way college taught the courses and evaluated course takers.

After a few semesters, I figured out my own way of learning about computer science, and I didn't change my way in order to get a good grade. My method also evolved a lot over time, but not around optimizing grade acquisition. It was for me to learn better. I wanted to learn my own way, even if it meant I won't get a good grade.

The idea came to me after the second semester, back in 2016, when I didn't go on a two-week new year's trip with my family and spent all of my doing two projects that we had for advanced programming course. One of them was making a Frogger clone game with Processing (a frog wants to cross the endless lines of cars while not being hit) and the other one was creating a web scraper that processed data and presented it in webpages (python, js, html.)
I remember at some point I had to make a decision, I could take the safe route to implement the frogger game's camera system, OR I could risk it and choose a way that I didn't know much about, but that could be more fun and informative. And I took the latter route. And didn't make it to the deadline. Got a 60/100 for that project. A classmate that started 2-3 days before the deadline got a 100. Objectively speaking, the classmate's project just worked, therefore got a 100. Mine just didn't work properly, although I spent a lot of time and learned a lot of things along the way. I wasn't mad at the classmate because they knew how to get a good grade. They were actually playing the academic game right.

But I fell in love with diving into code for hours. So I decided I'm gonna keep taking the risk even if it means not getting a good grade. Down the line, the same thing happened in our Operating Systems course. The project was modifying functionally of the XV6 OS which is an educational OS. But there, I got a 180 out of 100. I didn't care about the 180 as much as I didn't care about the 60. I just enjoyed my time writing C code and getting segmentation faults after segmentation faults while not being able to print anything in the code because the code was that deep of a level within the OS code.

I was really not good in the theory-heavy subjects for a long time. This was really bad in the academic setting because in my college more than 80% of the grades came from theorical exams.

I think I sucked because of these fundamental reasons:

For a long time I couldn't make myself focus on studying. I didn't have a method that worked for me, and I didn't try to concretely test and find a method. I think the reason was that I enjoyed pure coding so much that I spent most of my time doing that. So I didn't want to do non-coding activities. Which was not good. The nights before exams were the worst. I still remember the dreading feeling clearly.
I didn't know why I had to study what I was studying. And nobody talked about why. Courses rarely talked about the reason behind the existence of concepts. And on top of that they presented islands of information. Like a piece of memory that is allocated but never used and the language doesn't have a garbage collector and the OS is malfunctioning too. After a few semesters I just started to make the graph of my knowledge jointed, to the best of my understanding.

As I studied and thought more about the concepts, I really started to like learning theorical subjects too. But, I decided that I want to spend a lot of time and energy grasping the concepts and reasoning behind them instead of minor details that I know I'll forget. The reason was an observation I made on the top graders of our class that forgot most of the course contents a week after the semester.
I kept refining my way of studying. Eventually my last semester's version revolved around reading a lot of textbooks, but focusing on the keywords that I found in different colleges powerpoint presentations. So I was learning things that seemed more crucial to know. And the driving force was asking questions as well as writing briefs for myself. Filling notebooks full of notes was also really really nice.

Deeply learned concepts are not that easily forgotten. Concepts can be stored in your mind and be dissected as abstractions and later be transformed in many different mediums and scenarios within the computer science realm or even outside. For example, you can learn a concept from hardware design and apply it in networks years down the line.

There is a merit in learning and tracing the algorithm details as they expand your brain functionally, and I did that until I felt like I learned the thing that makes the algorithm special. I didn't go as far as memorizing the minor details. If the exam had a specific question of some small detail I would get a bad grade.

But funnily enough, some point after I really focused on finding my way for learning concepts, my grades improved compared to the the first semesters through which I had a shallower approach. I didn't fail courses as much as before. I even got a lot of As. But I just didn't care about those metrics. I just wanted to learn things.

Looking back at my approach today, I don't regret the decisions, but I think I could've done a few things;

I could have done better in asking more and better questions when studying things and doing projects. If I asked more "whys" and "hows," I would have had much deeper knowledge. They really make a huge difference. The more uncomfortable and insecure a question makes you feel about a subject that you're studying, the more it shows that you haven't grasped the idea behind it. Today I feel like I have a lot of gaps in my knowledge. I would love to read some textbooks if I can make some time.
It's true that I didn't care about grades. But the fact is, if I had spent just a tiny little bit of time and turned in some assignments 50% done, or even 10% or 5% done (any non-zero percentage), I would have not failed at a lot of the courses that I failed. It would have taken 15-30 minutes a week and helped me to not fail a course. With that being said, I don't regret failing the courses that I failed because most of the time, I learned new things about the subjects of the courses.

The way I studied/have been studying realms of computer science over the years, has changed the way I digest world as a whole today. And I love that.
Anyways, I just wanted to share it here. Maybe it helps someone out there too.

Making Custom Abstraction Units for Programming Languages

amu — Wed, 24 Jan 2024 13:29:33 +0000

Consider the concepts of composition, inheritance, encapsulation, etc, and how languages take in these concepts and create language units that utilize them. The meaning of keywords "class", "structs", and "interfaces" is different everywhere. Each language adds its own flares.

I was wondering why the devs of each language decide what they decide regarding language's fundamental units. Then I was thinking if I were to make my own units, how would I go about it. How would I even evaluate if a language unit that I designed was good or bad? Eventually, as a natural jump, I made a programming language to figure it out in action... just kidding... I just designed some units for an imaginary language.

That's what I want to talk about in this article.

First let's start by mentioning a few languages and how their units are different.

Examples

In C#, there are classes with single inheritance ability, and there are interfaces. There are abstract classes which are like a normal class containing only properties PLUS an interface that the classes doesn't implement and passes down to its children. Then there are sealed classes that don't accept children.

In C++, class A : public class B can mean either inheritance or composition. And there's no notion of single inheritance. There is a concept of friend class which bypasses encapsulation and allows a class to have access to everything within another class's instance.

Typescript allows for an interface to have variables, kinda like C++. But C++ doesn't have have a direct keyword for it.

Rust has trait which is like the C# interface. But Rust's traits can have default implementation. So more like an abstract class that doesn't have variables.

Javascr*** - don't get me started on that.

How to find out which approach is better?

Here is my goal: I want to find a common way to analyze a language unit regarding the concepts I mentioned before.

In the most abstract sense, a piece of code is either a data, or a behavior that works with data and as a result it may or may not change the data. It's either registers or instructions in the assembly-sense.

We can start by thinking about our two fundamental units of a language:

Variable (data)
Method (behavior)

Also consider the fact that a behavior unit can have default implementation or can be totally body-less. And additionally, a variable can be constant too.

Variables and methods can or cannot mutually exist within a unit depending on the language designers' choice. For example, in C#'s "interface" unit, only body-less behaviors and const variables are allowed.

So, here is the set of all of the behavior-side possibilities for a language unit:
{ methods without default implementation,
methods with default implementation,
no methods }

Here are the data-side possibilities for a unit:
{ vars,
no vars,
only const vars }

Finally, for a language unit, here are all of the permutations of data and behavior, calculated by multiplying the two sets:

(methods w DI, no vars) ---> BEHAVIOR HEAVIEST
(methods w DI, only const vars)
(methods w DI, vars)

(methods wo DI, no vars)
(methods wo DI, only const vars)
(methods wo DI, vars)

(no methods, no vars)
(no methods, only const vars)
(no methods, vars) ---> DATA HEAVIEST

We have 9 options for a language unit with different intensities of being data-heavy or behavior-heavy:

The behavior-heaviest unit is a unit that contains a bunch of methods with default implementation but doesn't contain any variables.
The data-heaviest unit is a unit that only contains variables and no behaviors.
And there's everything in between.

We can map them to examples already existing in different languages:

(methods w DI, vars) => typical class in most languages
(methods wo DI, vars) => typical abstract class
(methods wo DI, no vars) => typical interface

Making An Imaginary Language

As a thought experiment, we can take the most extreme sides of the range, and make a language that only has those two units (in addition to the two fundamental units.)

Here are our language's building blocks:

Single variable unit
Single method unit
Collection of variables as a unit
Collection of methods as a unit (with default implementation)

The next step is to define how would the connection between units be. There are the 6 classic types: inheritance, implementation, composition, aggregation, association, and dependency.

My theory is that only having composition and association relationships would suffice for our language. To me, composition means having a certain quality and association means just using something.

Let's code a short example; designing the logic for a small tower-defense game.

We can consider a bunch of variable-collection units (vc for short.)

vc health
{
    float remaining_amount;
    float max_amount;
}

vc transform
{
    vector2 position;
}

vc entity
{
    bool is_alive;
}

vc agent : has entity, has transform, has health
{
    int hitting_power;
}

vc building : has entity, has transform, has health
{
    list<agent> agents;
    int max_agent_capacity;
}

We composite the healthness to agent. So it will contain remaining_amount.
We don't composite agentness to building. building has association with agent, meaning that it just uses the object.

As for the method-collection units (mc for short), we add the following;

mc moving
{
    void move(vector2 amount);
}

mc attacking
{
    void attack(entity* atackee, int damage_amount);
}

Now we can complete the logical design:

vc agent : has entity, has transform, has health, 
    has attacking, has moving
{
    int hitting_power;
}

vc building : has entity, has transform, has health, 
    has attacking
{
    list<agent> agents;
    int max_agent_capacity;
}

I think method-collection units by nature are users of variables-collections, they don't compose them.

Turing completeness

Being Turing complete means that a language can solve any computational problem. The already existing programming languages are already Turing complete. Our language has actually less features than a normal language, as it has less inclusion in its constructing units. We can't just claim that it is Turing complete too, we must prove it.

Turing machines are cool because they can solve any computational problem. So if we prove that our language can implement the structure for a Turing machine, we have proven that by proxy, our language can solve any problem. Although the solutions might not be efficient.

Here's the gist of a Turing machine coded in our language:

mc tape_managing
{
    char read();
    void write(char symbol);
    void move_left();
    void move_right();
}

vc state
{
    string name;
}

mc state_transiting
{
    state goto_next(state* current, char read_symbol);
}

mc machine_running
{
    void step();
    void run();
    bool should_halt();
}

vc turing_machine : 
    has tape_managing, 
    has state_transiting, 
    has machine_running
{
    state current_state;
}

The code doesn't look nice for this use case. But it works. So this language can produce solution for any problem. They might not look cool, but they are there.

So what?

The abstract idea of what I talked about can be a useful thing to consider when designing software: using smaller units. Not as small as my language's unit. But, for example, having a less crowded class would be helpful to achieve a cleaner design a lot of times.
It is much much easier to overengineer and overcomplicate. This type of constraint by nature helps you practice design in a cleaner way.
For me, I also have too much fun thinking about abstractions. So I'll keep doing it.

How to Get Better in Design Patterns?

amu — Tue, 25 Jul 2023 21:28:55 +0000

The main idea is that studying a bunch of design patterns or general design ideas in bulk is useless, because your brain has to dissect those abstract things and learn to detect them as "symptoms" on concrete problems when you are doing real tasks on real code.

If you want your brain to naturally come up with a certain design pattern as a solution, it has to try use it in repeat, through iterations. Just like how you learn new vocabulary in a language: you review words a few times until they become second nature and you can naturally use them when you speak.

I have been trying this method on myself and programmers I was mentoring in real-world production environments. And it's proven to be working. It's really simple and fundamental in principle.

Here's the method:

1) Acquire the knowledge of the existence of a single design idea.
2) Write a piece of code the way you normally do.
3) Review your own code and try to detect bad things about it.
4) Refactor your code. Think of all the design ideas you can come up with for that specific piece of dirty code.
5) goto 1 (enough times).

"Enough times" is totally relative. Relative for each design pattern, and relative with one's fundamental knowledge of software design.

Maybe after all, this is simple, but it takes some time. The truth is becoming genuinely and fundamentally good at programming needs time and mindfulness. I am also far away from ideal and do practice this on a daily basis. It's a fun part of the process.

Also you can easily find the failed examples of "learning in bulk" within the college students who study a bunch of design patterns for exams but forget all of them a week after. Moreover, they aren't also taught to use the abstract ideas in real world and concrete problems.

I hope this will be helpful to someone out there.

How to Study Large Code Bases?

amu — Wed, 05 Jul 2023 21:43:28 +0000

I remember 5-6 years back, I was working on a large code base for the first time. The project had a short deadline and our task was to literally refactor the whole repository. I freaked out the first week and messaged our tech lead to ask for advice on how to tackle this code! I was SO STRESSED.
Starting from then, throughout the years, I’ve tried different ways to face these initially-intimidating code swarms! I am sure they will evolve further over time, but I want to share them now, maybe it will be useful to somebody. Frankly, now I enjoy large, challenging code bases A LOT.

The fundamental statement is this: for a project that has been worked on by a team of devs for hundreds of thousands of hours, you just can’t learn the whole code base all at once. So we have to find ways to do it bit by bit, just like the concept of divide and conquer algorithms.

Here are a bunch of ideas I have used, that you can mix and match to your liking:

Following the Footsteps

A huge code base has grown over time. You face the end product, but there’s a history to it. The best way to go about this is using the version control and seeing the change history in the most granular sense possible. If the version control is healthy, following the micro-changes won’t be intimidating. Moreover, since the original authors are attached to the change, you can ask them questions too.

Do Small Tasks

Most likely, when the code is huge, you are not expected to know all of it. You specialize in parts of it and increase your domain of knowledge gradually. So for step 0, a good way would be choosing a small task in isolated components of the system (as opposed to a task that involves knowledge of multiple parts).
In a commercial production environment and company, this happens naturally when you join a team. For an open-source project, this is close to “low-hanging fruit” issues which are basically problems that are beginner-friendly.

Ask Specific Edge Case Questions. Be edgy.

Asking tricky questions is truly a skill. As you practice, it becomes really enjoyable to use your x-ray vision for edge cases. The edgier the question, the more knowledge gained.

Example: Let’s say you want to learn about a class in the code.

Here is the “vanilla” question:

What are the attributes and the methods?

Here’s the edgy version:

What is the public interface?
How frequent and in what situations the interface is used?
What are the classes that this class is connected with? (association/inheritance/aggregation/any connection)

Here’s an even edgier version:

What’s the runtime flow of this object?
- Who creates this object?
- When is it created?
- How long is it alive?
- When does it die? We can get even edgier:
With my current knowledge, what criticisms do I have about the class? How would I make it better?
- Is the public interface / private things properly laid out?
  - Are they cohesive enough?
  - Are they coupled to outside reasonably?
- Is the abstraction okay?
  - Does this class have things that can be moved to the higher abstractions? (like move things to the base class or other interfaces?)
  - Should I break down this class to smaller objects? Like, does it obey the single responsibility ideas?
- How would I improve the namings of attributes and methods within the class?

(Note that, you probably won't literally refactor the class. But when you have the vision of improvement, your mind dissects the current state of the class pretty well, and then provides even further ideas on how to make it even better.)

Draw Diagrams

Diagrams are underrated. It’s shocking to me how under-used it is when demonstrating how a code works on the internet. The standard diagrams in the software field follow the guidelines of a language referred to as UML. UML provides a bunch of diagrams, each being applicable to different situations: sequence diagram, class diagram, use-case diagram, deployment diagram, collaboration diagram, and many more. If you want to learn about UML, Martin Fowler has a great short book on it called UML Distilled. (His website/ Amazon)
You don’t have to use UML. You can use any visual way that comes to your mind. UML is just a standard language that engineers know all around the world.
As for the medium, you can use paper, but it’s not a very modification-friendly choice. I personally like to use draw.io, an open-source, free, online diagram platform. There are a bunch of paid ones available too.

Use Breakpoints

If you want to dive into the runtime flow of the code, breakpoints are a huge help. It all depends on your IDE, your domain of software (web, desktop, etc), but the concept is the same. The most primitive way is to use logs. But oftentimes, breakpoints give you much more information on the call stack, variable values, etc.

Explain the Code to Others

This is a huge, huge help. This method is scientifically researched a lot and is proven to be highly effective (Google Scholar).

Edge question: to who?

To the authors of the code itself, if they’re on your team.
- They can correct you if you’re wrong, because they literally wrote the code.
- They can provide the perspective on why they coded the way they did in the first place. The knowledge of the context helps a lot. For example, the code may be dirty, but the context might be that they didn’t have enough time. So it’s natural for you to not understand the code easily.
If you don’t have anyone around, you can talk about the code loudly, as if you are recording a video. Even better if you can have a friend to listen to the code, maybe they gain something out of it too.
I use this a lot: Intentionally explain the code to someone who has no idea about the project and ask them how much they understand your lecture. This provides insights in 2 ways:
- Can you improve the way you communicate technically?
- Did you understand the code properly in the first place?

Mix and Match

You can mix and match the ideas in any way you can imagine. Like, you can design some really hard questions then, as for the answer, draw specific diagrams and then present them to a friend.

That’s it for now

I will probably add more to this article later. I hope it helps someone out there, because I personally really struggled a lot in the beginning.

Analyzing GTA Vice City Source Code, Part 2: Vehicles

amu — Tue, 04 Jul 2023 14:05:12 +0000

I'm reading the GTA Vice City code that was decompiled by a group of people for fun (available publicly at github.com/halpz/re3). Minimal code was added merely to fix the bugs, so it's really authentic. The code base is really huge and fun to wander in.

I'm going to share my design and architecture analysis on the code base by asking questions about each episode's subject and providing answers in a way that you don't need to read the whole code.

This episode is about vehicles that construct a significant part of the gameplay experience, therefore this article is HUGE and took a lot of time to write. The goal is to share some ideas that can be useful for you when you design software, not to share every detail.

Let's start off this episode by answering the question I had in mind since I was 8-9 years old:

1- Does the game intentionally spawn similar cars to the one you drive?

Turns out, nope.

First of all, the concept of LOD (level of detail) is used in the game. Basically, the area that isn't in your certain vicinity, doesn't have any functioning NPCs. LOD is a way of structuring and optimizing the whole game and involves a lot of things in different layers of the software. For example, the models' textures in the distance are rendered with a decreased quality for optimization purposes, or the sound effects of distant events aren't played, just to mention two use cases. We love LOD. Depending on the game, LOD's usage and indications change; for example in the Sims 3, the agents that aren't near you are still "living," but the resolution of their actions may vary. For example, they may only do actions regarding satisfying their basic needs like hunger, rather than doing minor activities like viewing a statue (in the game, it's much more complicated than that) but in GTA Vice City, there isn’t a karma system or anything, so NPCs are stateless and can die/spawn in the spot.

Getting back to the subject of spawning cars, less than 30 vehicles are alive at one moment, and only around you. In trajectories and directions based calculations on the player position (whether it should be behind you, in front of you, etc.)

Note that police vehicles that chase you when you have wanted levels above 0 are amongst those 30. If you don't have a wanted level, cop cars are spawned with a threshold. So as gang cars. Both of which depend on the zone that the player is at. (Bonus: the number 30, is an rvalue, just a hardcoded number, in a for loop. Not a [const] variable.)

For generating a new non-special car, game mainly takes the following two concepts into consideration:

Player: speed, wanted level
Zone: time of day, zone population density, gang type for the zone (correlates with a car model), etc

(It takes many more parameters, but these are the gist of it)

In the case of cars, there are 9 "ratings" for how luxurious they are. Same as for boats and other types of vehicles, but with different values. There is a car frequency array holding information about the number of spawned cars within each rating class. Through a very dirty sequence of calculations, a car model is chosen logically (it doesn't have anything to do with 3d models yet)

The player's current car type isn't used when the game is spawning new cars. However, some of the other properties of the player's car, such as speed, are used to calculate the transform properties of the newly spawning car.

I would say this part of the code isn't that educational and inspiring from a software design and architecture standpoint. The main things to take-away would be:

using LOD
using map zones to introduce variety in NPC behavior/presentation
using frequency as constraint parameter

The code for this part was not clean to say the least. It doesn’t mean anything other than the fact that at that time, late 90s - early 2000s, they developed games without the vision of constantly having to ship updates afterwards. The whole development model was based around heavy-weight, waterfall processes; not the agile, iterative, constantly-changing-requirement development models that are common today. And it’s actually the better choice for this type of project. I will write up my ideas further around this subject later.

Maybe the reason for me feeling this way was that there aren't a lot of car models in the game.

2- How do cars that are out of sight get removed?

So this is a follow up to the LOD concept in the previous question and it’s about removing useless things out of sight.

There is a "vehicle pool" which is a singleton container that has pointers to all living vehicle objects. Amongst the pool, the objects are checked and removed mainly based on how distant they are to the player.

The further question is, where and how frequent is the said function called? It’s called in the main game loop. Every time the loop iterates, this method is called and cars are cleaned up. You could say that this method is the heartbeat of the whole game. The iteration frequency is around hundreds per second (it’s more complicated than that, but you get the point.)

Game loop is one of the fundamental concepts, both in game design and game engine software architecture. In game design, it’s one of the fundamental questions you have to answer when coming up with the idea of your gameplay. In software, this pattern, in the most naive sense, involves structuring the game code to a setup phase, a loop, and a shutdown phase. The loop can contain anything within the game flow: updating logic, getting joystick inputs, rendering stuff, updating the ui, etc.

The key ideas that can be useful and are worth looking further into are:

object pool design pattern
game loop pattern

3- How does a vehicle controller work? (physics + inputs)

General Structure

Each type of vehicle has its own controller. All of them are children of a "vehicle." Vehicle itself is a physics object
and a physics object is an entity. Being a child of an entity, enforces it to implement a method referred to as ProcessControl. This method is called by the world object as it's going through all of the alive entities in every frame of the game.

This level of abstraction hierarchy is good for the use case of a vehicle:

Being a physical object gives it properties such as moving speed, mass, buoyancy, etc, along with respective methods.
Being a vehicle gives it properties such as steering angle, gas pedal, brake pedal, horn/siren, gun firing time, gear, etc.
Being a specific vehicle type mostly means using the properties and methods passed on by parents as well as adding to them, in concrete ways. For example, cars focus on specific calculations on their wheels because two wheels are connected to the engine and two are used mainly for steering, any of the four can be flat tires, etc. On the other hand, boats don’t have wheels, but they have specific calculations regarding buoyancy, helicopters for floating in the air, and so on.

For this question, I will talk about cars as an example, you can read about the other types such as helicopters in the code. The class for cars is called Automobiles.

Input Control

The Automobile class handles everything that you can possibly imagine about a car: inputs - gears - hydraulics - collision - horns - doors - damages - burst tyres - blowing up - horn sound - ...

For this question, let's just focus on inputs from the player through either the keyboard, or the joystick.

Being a child of the vehicle means that the class must implement a virtual method for handling the keyboard input. The input handler for a car does many things, and one of most important amongst them is steering to left and right.
For steering, the keyboard input means nothing on its own because it's just a float value between -1.0 and 1.0. It must be converted to an actual radian degree value in order to be applied to the actual car's rotation amount. The new amount isn’t replaced by the old amount, but it’s done through clamping which ensures a smoother transition and is used a lot in games.

Note that, the result of all of the calculations within this method is just assigning some values to some variables such as m_fSteerAngle and nothing more than that.
The actual place that the variables are used is in the process control method that was mentioned previously. The reason is that the user’s input isn’t the only thing that affects a vehicle’s properties; a lot of other non-input stuff can cause change for those variables, such as having a flat tyre. In the end the process control method is updating the car and doesn’t care how and why the variables’ values have changed, it just applies them.

A question/idea here would be, are the value modifier methods and the value applier methods working in the same thread? If you think about it, you can have these two sets of methods manipulated concurrently by using mutex and such. However in the game, these types of logics are handled in a single thread. It can be for many reasons, let me know and I can write more in some OVA episodes.

4- How does vehicle collision with world objects work?

The concept of collision detection within the game involves a lot of different types of physical entities within the game. I will have a separate episode for collisions in general.

5- How does the interaction with the car doors work?

First, there’s a design decision worth mentioning about the code. As mentioned previously there’s a chain of inheritance for the automobile (which is entity -> physical -> vehicle -> automobile) but the chain doesn’t continue to extend for the specific types of automobiles such as a bus, police car, taxi car, tank, etc. This means that all of the specialties of these types need to be handled within the same class. This can turn out to be messy if there are a lot of differences in the fundamental way each child class functions. For this case, the main differences aren’t that much, and are handled using if-elses and other measures. But for your own code, you have to think about the requirements at hand and consider a sweet spot for the amount of abstraction you create. This amount can always change as we work more on the code base and add more features to it. We just don’t want to over-engineer and we don’t want to under-engineer either.

Regarding doors, the automobile class considers 6 doors. Even though, for example, a Ferrari has 2 doors, and most cars have 4 doors. The reason comes back to the thing I mentioned in the previous paragraph.

What do we need to consider about a car door?
Is it missing? (like to use to measure how damaged the car is)
Is it open/closed?
Is it ready to be used? (like is the car stopped so that you can open it or jump out of it, etc)
Where is it located? (front/normal back/"special" back (e.g. ambulance))

It might seem obvious, but it’s worth mentioning that as for the answer of a lot of these questions, the class only needs to provide getters that are used by other classes (such as IsDoorOpen(DoorPlace). The car itself doesn’t use any of those properties unless it makes a difference on its own functionality. If not, it provides the information to other objects and it causes something in the game to change.

Within the automobile class, the doors are mainly used for the animations. There’s a method for handling open doors. This method doesn’t need to be constantly called, like the methods for input handling. So these methods are called from outside whenever the game logic knows that something happens to a door and wants the target car to handle the changes. For example the player class calls the method of a vehicle instance when it opens the door of that vehicle by sending a command to the command bus.

The door animations are dynamic, meaning that they are different based on vehicle models and different within the same doors in one model. So the code basically rotates the door part of the 3d model, with the hinge being the pivot point, in a certain duration.

Now, when a pedestrian is opening a door, we need to have animations for the door, but more importantly, the ped’s model has an animation too, and these need to blend together. I’ll talk about this and animations in general later.

A very important question to have a clear answer for is this: how is a specific car and/or door accessed from outside? Because I mostly talked about the class itself. There are a lot of living instances of that class. Answer: a ped has direct pointer reference to the vehicle object its driving as well as the knowledge to the door it has accessed the vehicle through (it’s an enum {front-left, back-left, etc}). Basically every interaction between objects/world is done either by events firing in the bus or direct pointer references.

6- How does the vehicle dynamic sound effects and radio work?

It was talked about in episode 1.

7- How does a car change colors?

Or more technically phrased: How does the car 3d model and textures properties dynamically change in the runtime?

This is applied to when a car is spawned or when a previously-spawned car wants to change colors (like in an spray shop)

When we only have one class for any automobile, how do we differentiate the 3d models of a Ferrari and a Chevrolet? Being an entity enforces children to call a parent method called “Set Model Index” indicating the model id. So it is used by many more things other than automobiles.
Let’s say you have a Ferrari car model that you want to change the color of. Knowing the model’s logical name within the code, you can use a class called VehicleModelInfo, through which by indicating the model name, you can get access to and manipulate values specific to the model. When you pass the model name to VehichleModelInfo, it searches the registry of all models properties and finds the exact model you’re looking for.

Under the hood, on the rendering side, it does have things to do with materials and shaders, but the game logic doesn’t know much and doesn’t care about that. VehicleModelInfo and its parent, ModelInfo, have a lot to do with rendering too. I’ll talk about rendering in a specific episode. But I think it’s useful to mention one last idea about it here for now:
You don’t want the rendering engine to have a lot to do with your logic. Conversely, you don’t want the logic to be concerned with rendering that much.
At the same time, sometimes you just can’t avoid completely isolating the two and having some rendering functionalities and settings on the logic side and vice versa. So, at least, we want to shove all the rendering-related settings of the logic layer to one or a few specific places and shove all the logic-related settings of the rendering layer to one or more specific sides. And we want to make these two shoved sections as painless to communicate as possible.

8- How is the car damage realized and handled?

For a car the damage can be applied to doors/hoods/lights/all of it (like when it blows up).

There’s a damage manager object inside the automobile class which basically sets the status of damage for each damageable part of the car. The parts include the engine, 6 wheels (not 4 as explained previously), lights, and panels (hoods). The status of a damage is an enum object indicating how severe it is. It also provides methods for modifying them. For example, applying differential damage to a certain part, resetting damage, applying max damage to all parts all at once, etc.

As for blowing up the vehicle as a whole, a non-pure virtual method exists in the base vehicle class. For an automobile, this method is implemented to:

Apply max damage to every part
Shoot the doors and wheels flying
Shake the camera
Kill the peds in the vehicle
...

9- How do you steal a car?

(FBI, I’m talking about the code of some game, not about real life. Don’t take it literally bro)

As far as a vehicle is concerned, it doesn’t matter if the car is stolen. A vehicle has a pointer to its owner and vice versa. If the vehicle’s owner isn’t the ped that just got into the vehicle, it means the car is stolen, and as a result, an event gets fired to the event bus. And after that, the ped will be assigned as the new owner of the car. Everything I mentioned is handled within the pedestrian code, not the vehicle.

10- How do special cars missions work? (like taxi and ambulance)

I will talk about it in a future episode. I call these car missions, as well as rampages, collectibles, etc, “open missions.”

NEXT EPISODE:

I did delete some of the questions I initially intended to include because it got too long. However, there will be more episodes. As you have seen, there are many topics that can be covered. Since this episode was rather heavy, the next will be smaller. The topic will be about crime handling and wanted levels.
You can comment your ideas and questions in general. I’ll be happy to talk about them!

I also have some ideas on having OVA episodes, in which the content will be about super niche or abstract subjects within the game. Let me know if you have suggestions.

Edit (Jul 26th, 2023)

The goal of this series was to share practical knowledge about software design with the help of a real-world project. Looking at the stats, the series doesn't have enough engagement yet after a few weeks of posting, maybe it's me, or maybe it's the subject matter. In any case, I take this as a failed pilot idea and discontinue the series. I will try to find other ways to spread the word about my passion which is software design and architecture in another form.

Edit (Mar 24, 2024)

Okay actually it has picked up traction. I will continue this series lol. But I'll work harder to design higher quality questions.

Analyzing GTA Vice City Source Code, Part 1: Audio

amu — Sat, 24 Jun 2023 17:58:34 +0000

I'm going to share my design and architecture analysis on the code base by asking questions about each episode's subject and providing answers in a way that you don't need to read the whole code.

This one is about audio-related stuff in the code. If there are further questions that you come up with, let me know and I'll append the answers later!

1- How is a certain sound asset addressed in the gameplay logic?

There are gigantic enums that consist of logical name for all of the sounds used which involve SFX, music, dialogues, mission audio (sequentially), etc. Even for the player's mood, there's an enum indicating the respective sound effect.

Random fun fact: Player mood, for example, has effect on the sound effect of the guns.

2- How are the sound asset files loaded?

The address for the literal WAV sound files are hardcoded. There's a class called Sample Manager which contains the addresses which are stored as static char arrays referred to as "Name Tables" (so it's basically an array of char[MAX_STR_SIZE] as for the string of the file address.)
The items of enum that was mentioned previously match one-to-one to the files in name tables. When a sound is prompted to be played, the enum item is casted to int, and used to access the name table item. The given file address is fed to the sound player function calls (such as AIL_open_stream())

3- How is a sound actually prompted to be played?

Basically using the central command bus of the whole game. For each type of sound, certain commands get sent containing payloads indicating the sound type item.

4- How are the sequential sounds played? (Such as dialogues)

Simply by playing single sounds and increasing the indexes sequentially and sending commands from the logic to the bus in order to preload a certain mission audio files and then playing certain slot of the sequence.

5- How does the radio work?

In the code, it's referenced as "music" rather than radio. The term radio is actually is used for the police radio (like the one that plays when you get into police vehicle.) When you get into taxi/police car, instead of normal music, the sound of the police/taxi radio plays.
Playing music in the vehicles is one of the MusicManager class' duties. MusicManager is a global static singleton instance. The term music is used as some audio asset that is not a SFX. Since there's always one music playing at the time, there's a general method for playing the current track, referred to as front end track which gets a track id as the input. This method is called several times because many differnt conditions in the game start any music; such as you literally starting the radio, mission ending, you changing sound/radio settings in the menu, etc.
Bonus:

Fun fact, there's a method for retreiving player's favorite radio station (by keeping track of the station with max amount of listenting history). It'll be used to be set as the default station when you get into a vehichle.
Music manager also manages the background music for places, such as the Malibu club.

6- How are the sound settings in the menu applied in the gameplay?

There is a massive part of code which deals with the front end stuff, for example the menu UI. So, drawing sprites, getting mouse, joystick, and keyboard inputs happens in there. And when you press the respective buttons to for example, mute something, or change active stations, within the front end code, the method of singleton object of music manager gets called.

7- How does the vehicle gear system coordinate with SFX?

(First of all, there is a lot more to vehicles. I'll talk about them later)
For everything that's dynamic with sounds, such as vehicle gear, or when it rains on them, or reverb in general, etc, these things are handled by the AudioLogic. There's a method that handles the vehicle engine sounds. This gets called by the system in charge of updating physical sound objects. The mentioned method considers a bunch of parameters such as engine sound type, current gear, is the vehicle slowing down, etc, and manipulates a sample to be played in a sound channel. The same thing happens when you're in the reverse gear.
The vehicle engine sound is processed alongside the other properties of the vehicle such as for example, whether it has as a flat tyre and its implications. I will talk about vehicles thouroughly later.

8- How does the dynamic reverb work?

In different occassions, within the audio logic, a method is called to [de]activate the reverb to toggle the reverb activation state of the next samples which the the audio manager will going to ask the sample manager to play. The wetness amount isn't dynamic.

9- How are the sounds literally put on the device's speakers?

All logic and gameplay aside, there is a sample manager that is in charge of everything "sound rendering" if you want to call it that: such as setting channel volume, channel pan, sound stream management. Sample Manager by itelf is a base class with OpenAL and Miles (Miles Sound System Dynamic Library) implementation child classes. The mentioned children are the lowest level the code gets to the physical speakers of your device. The libraries provide methods for interacting with sound drivers.

NEXT EPISODE:

The next part will be about everything concerning vehicles. If you have specific things you want to know regarding vehicles in the game, let me know and I'll include them!

I ditched what I worked on for months...

amu — Fri, 27 Aug 2021 18:18:36 +0000

...but I didn't threw it out.

I worked on Ava sound engine for quite some time. I made it from scratch, in C++. C++ is a good choice for audio-related programs, such as the DAW that inspired development of Ava. I decided to separate the DAW's interface with its processing unit, and Ava was born there. It's still in the development.

But Ava was also intended to be used for another project I've been working on for two years too: a digital IoT-based hardware synthesizer. It was/is my university thesis project.

The idea was to turn data from nature, into sounds. But all through the internet and wirelessly.
The basic flow of the device is that there are a unlimited number of ESP8266 (something like Arduino) devices that each have a sensor connected to them. They share their sensor data in a network connected to the internet.
There is a processing unit, a raspberry pi, which receives all of these data and turns them into sounds and MIDI signals. The sounds can be heard when it gets produced, but you can run the MIDI signals into other instruments!

And there is a dashboard that you can use to manage all the sensor nodes in the network, as well as controlling how their data is processed and turned into notes; so you can choose which musical scale the device makes notes in. Or which sound wave type the sound should have. Or how long each note should play. And more!

I intended to use Ava as the sound engine for device. But it was too hard to integrate it with all the python code and have them exchange data without bugs. So I had to ditch Ava in this project. It was sad but it made the project much more easier to develop and flexible.

Anyways, the synthesizer is called "Natural." It's also fully open-source. The repo is here!

It's not done yet, but it's so close to version 1 release! I don't know how many hours I've worked on this, I know I'm having fun tho.

I'll write more about it when the version 1 gets ready!