Architecture: quality attributes and driving factors

[WildWeazel]

This is the first of a series of big-picture technical discussions about the scope, architecture, and data modeling of C7. About a year later than I had wanted to get started on these topics, but better late than never. Please do not take these posts as authoritative or final. I'm writing up all of this here to get your feedback.

---

First I want to discuss the driving factors of the architecture. These are the quality attributes and certain high-level functional requirements.

There are many quality attributes, and they often require tradeoffs. Not all are relevant or essential for a given system, nor would it be possible to fully satisfy all of them. Part of systems architecture is balancing the competing demands of these attributes, and so a good architecture requires that you know which attributes are essential. Of the common quality attributes, I consider these most important for C7:

• Portability: The could should be reusable, and the game work the same way, on all major PC platforms that Godot 4.x supports. This one is largely provided for us by the choice of engine, but we should steer clear of platform-specific code.
• Extensibility: The game should provide a framework and clear integration points for new mechanics to be introduced both during development and by advanced user modification. The architecture should support continuous and incremental change so that new systems can be introduced at any time.
• Modifiability: The very broad "ability to be modded" and all that that entails. This should include different levels and scopes of modification from runtime options to data files to scripts to core components. Hard-code and assume as little as possible in compiled code.
• Configurability: Distinct from game modding, the program itself should be highly configurable by the user before or during runtime, through persistent files and/or in-game settings.
• Modularity: Game mechanics and other high-level functionality should be split into distinct, well-defined modules to aid in both implementation and reconfiguration. At certain levels, modules should be interchangeable with different implementations provided either by the game itself or user scripts.
• Interoperability/Compatibility: The game should allow original C3C files to used, either directly or by automatic conversion. It should be both visually and behaviorally consistent with C3C when using those files, essentially meaning that a C3C mod can be reused as a C7 mod.
• Maintainability: The design and code should be easy to understand, debug, and update. This is a long-term volunteer project, and people don't want to spend all their time trying to figure out someone else's old code. The code and design should be well documented and follow agreed-upon standards.
• Testability: The game should be constructed in such a way that every part can be tested in isolation without spinning up a full game. This includes user testing and, whenever practical, automated unit or integration testing. Automated tests should provide high confidence that game features are working as intended.

And these are attributes that seem less essential but still relevant:

• Usability: With the overall game design and UX already a known quantity, there's limited space to address usability. Provide user-friendly enhancements to the UI where possible such as iconography, tooltips, menu options, shortcuts, customizable controls, and so on.
• Accessibility: Similar limitations to usability, but we should reach as wide an audience as possible. We should make reasonable efforts to provide accessible interfaces, such as colorblind help, screen reader compatibility, font and UI scaling, etc.
• Composability: Related to modularity, this is the ability to recombine components to satisfy different use cases. The game should allow mechanics, mods, scripts, etc to be selectively enabled or replaced to implement different types of gameplay or potentially emulate other games entirely.
• Fidelity: In this case, fidelity to C3C as we understand it, excepting bugs and other intentional deviations. This would be demonstrated in how closely a game looks, interacts, and plays out like an equivalent game in C3C, allowing of course for differences in randomness and AI.
• Robustness: In short, "don't crash to desktop when there's a mistake in the pediaicons." The game should recognize and cope with errors as much as possible, and degrade gracefully within reason. Depending on the case this may mean showing default placeholders, ignoring elements, blocking out features, or at worst presenting detailed information and cleanly returning to the main menu.

Other factors which influence the architecture include:

• Open-source/non-infringing: All assets included in the game and repo, from source code to dependencies to media, should be open-source and/or freely redistributable. We must not include any content that is derived from original Firaxis or other copyrighted files, and ultimately should not require anything from outside of our distribution.
• Human-readable data formats: Data at rest should be stored in plaintext file formats as much as possible, in a form that is accessible for basic modification without specialized tools. So far we have assumed JSON for data and are considering Lua for scripts.
• Performance: Late-game turn times and hard numeric limits are commonly cited problems. The design should take advantage of parallelism and caching to improve performance of turns, and scale well to allow more content.
• Online multiplayer capability: Interacting with a remote instance will mean either a client-server architecture, or a means to sync game state. The game's state machine, data structures, and async interactions must take this into account.

That's a lot, but I'm sure I've overlooked some. In general, these seem to fall into two broad categories: things that improve on the implementation of Civ3 for the modern player, and things that provide greater mod and development capability. Let's discuss more about what these attributes should look like and how they map to concrete design and implementation decisions.

[QuintillusCFC]

All right, so that all sounds well and good, but I count 7 items in the first section (not counting Portability as it's "free"), and 5 in the "less essential but still relevant"; "Performance" and "Online multiplayer capability" are also ones that could require significant effort.

To me that seems like a lot of things to be considering for a project with the amount of resources we have. If I put my project executive hat on, I'd be asking, "Okay, but if you had 3 essential and 3 less essential but still relevant, what would they be?"

I also notice that a lot of the "essential" ones focus on flexibility of various sorts. While we do want to have extensibility and mod compatibility, I think we should be intentional about making a game, not a game builder. We should try to make it extensible in directions we anticipate it realistically being extended, but the "new mechanics being added by advanced user modification" is one that has me wondering, "is this really realistic, especially given our team size? What are some examples, both in goals and in that being done in actual games, and for the latter what was the development team size?"

A large part of the concern is are we ever going to get a playable game if we have too wide of ambitions up front, hence my "lots of scope implied here" thoughts. It's a balance because a playable game with a crummy architecture is never going to evolve much, but a beautiful architecture for a game that isn't playable is going to make it hard to attract enough interest to get to that playable game.

(Yes, I am the "let's try to do fewer things at a time" person...)

[QuintillusCFC]

I should clarify that I don't disagree with any of these as good things to aim towards (other than maybe the new mechanics via mods), I think it's just a little too big of a target to be realistic, so I'd like a more focused target.

[WildWeazel]

Fair points. I'll defend my reasoning before answering your question.

First, this list is intentionally ambitious. As the self appointed architect and an idealist, I'm aiming very high here knowing that we're not likely to hit all these points to my full satisfaction. Attributes are not really tasks you can assign, and with a volunteer crew there's not much I can do to enforce their implementation aside from calling attention to the relevant design decisions. Since the default architecture is "big ball of mud" with few positive attributes, my hope is that by emphasizing all of things we should ideally address, we'll land somewhere in between and better off than if we hadn't considered them. We can always de-scope and temper our expectations, but ambitious technical write-ups are a lot cheaper than refactoring to address an overlooked attribute.

Second, attributes are not features and have a different relationship to scope and effort. These are mostly things that affect the "how" of design decisions. If considered appropriately early they can be folded into the functional requirements (this isn't waterfall logic; agile development just shortens the cycle from requirements to delivery) and implementation of each feature. Some certainly do mean more work, eg. robustness usually means writing a lot of error handling code, but it's not likely to be linear. Portability as mentioned is almost free as long as we don't add platform-specific code. Likewise both open-source and human-readable just restrict some of our choices. Maintainability and testability are mostly functions of good design & coding practices and documentation.

Third, there's quite a bit of overlap between several of these attributes so again I don't think the relationship to scope is linear. At a glance: extensibility, modifiablity, configurability, modularity, and composability seem like a lot of the same code or at least class design.

All that said, if forced to choose 3 from each tier I'd have to go with Portability, Modifiability, and Compatibility as essential (those are basically the driving factors I identified for creating C7 in the first place) and Usability, Fidelity, and Robustness as secondary (as those provide a "better than Civ3" player experience to really make it worth playing).

[WildWeazel]

Also my first point kind of applies to your concern about game scope as well. I've thought of quite a few concrete examples of extending the game, which I intend to write up as design case studies. Most of them are features that we've seen in similar 4X games.