v2.0 Proposal

Summary

Over the past few months, I’ve been working on a rewriting the entire user script to a large degree and I’m now looking for support to move development to the new code base.

Motivation

Looking at the existing state of the user script, I would claim that it has far outgrown the concepts that were put in place when it was first implemented. There are some major issues with it, that hinder future development and make understanding even the current state very challenging.

The code base is littered with tons of small mistakes that go untreated, because nobody can understand what the code is trying to do. There is duplication, because new contributors have implemented things that were already solved, but they couldn’t see that, as understanding the entire code base is very difficult.

One of the key issues with the existing design is the reliance on the huge options object. Not only does this dictate the options themselves, the entire UI is generated from the same options object, making it impossible to make certain UI adjustments, without affecting the business code.

Some areas of the options object are even shared between automation sections (like the resources) and which elements are required for each section of the code that uses these options isn’t understood easily.

This state of affairs also leads to new contributors just following the example and contributing more code with cryptic variable names, zero comments, and which adds internal design elements where they see fit to make things work.

The code style itself varies dramatically, as new contributors have used newer JS features, while not bringing the remaining code base to the same level. There’s some async/await sprinkled in the code, other parts use explicit promises. The entire code base still uses var for variable declaration and relies on variable hoisting in several places to make things work. Semicolons and bracing style also changes throughout the entire script.

Efforts

I’ve broken up the script into its core components. In the process, I’ve rewritten everything in TypeScript to make large-scale refactoring safe. The benefits of this process alone were immense. Now you can click through each call and get clear information of what information is expected and passed.

The entire Kitten Game API that is used in the script has also been marked up through type definitions, thus ensuring that all calls into the game are correct and future changes in the game can easily be tracked to all consumers that need to be updated.

I’ve reverse-engineered the entire code base to the best of my abilities and write comments for everything. This part took the most time in the entire effort and there are still places in the code that are unclear and likely need to be rewritten from scratch.

The UI is now a discrete component that is no longer generated from the options object, but constructed manually, to allow for free design. This finally enabled one of the features I wanted to add for a long time: Subsections with headers:

I’ve also spent quite a bit of time to make the development experience more pleasant, by deploying a container that serves the game and automatically injects your current development version of the script. This also allows for automatic injection of any saved game state and Kitten Scientists options, to debug specific features of the script.

The current state is available in my fork: https://github.com/oliversalzburg/cbc-kitten-scientists

Future plans

So far, I’ve only made minor changes regarding the functionality of the script, to make it easier for other contributors to assess how things moved around.

I want to further clean up the UI and improve the console output to make troubleshooting issues easier for users of the script.

Some of the great features that were contributed in the recent months still need to be reintegrated as well.

I fully expect other contributors to hate the entire effort, because it uses complex tooling and prevents being able to just “hack” on the script, but I feel this is necessary to make maintaining it viable in the long term.

Would love to hear your thoughts. Cheers ❤

---

TODO

The following commits need to be integrated downstream to reach feature parity (project was forked from 7ba6b747ae58ab514f377e81a9d3060cc72614b8):

• 0f54168d699d28a04ae0f2d64f28959989d4c0bd
• 5d43646957066074d61d48583b765de9e630b118
• 0581a95e05a2187e13d940902b3940fc09cb5f96
• 4064c62e15b4a2f2a9527e6154141ddebefd9a5f
• 90018e6537851e1ea1dea0973564e9d40015b87f
• 9bb71237ff7c4896c31aa28ee9010741a480199d
• 85f452a1d41ca1c338d577533b78b15d27097cf5
• 937fb24dacd6f5d912f44d32398de79abbabc739
• 8f1478ea63e14c9e91da02c245324fc40e6c20f9

[cameroncondry]

This is entirely amazing. I love the move to TypeScript and you’re very right that this is needed to keep the script moving forward. I’d like to echo your sentiments on the script’s UI and style updates to the game screen. Initially, there was a need to solve some nagging issues, but those are now very long gone and I’d go as far as to say that any alterations to the game styles should be removed. Simply leave enough to make the script options easy to understand and use.

I don’t have time to contribute much to the actual development of the rewrite, however, I would love to provide a code review and help answer any lingering questions. I might be able to even answer some of those questions on unclear sections of the codebase. I took a lot of liberties in balancing the script to my own tastes, which made the code very opinionated.

When I have a bit of time I will look over your fork and let you know my thoughts there as well. These days it is fairly easy to integrate modern DevOps practices that would make the coding experience much easier. The way I envision it would be the users only need to make sure node/npm is installed and then start a runner that will compile and refresh the code as the developers are working. I have garnered a lot of experience lately in making very easy-to-use and smooth development environments and would love to see what you’ve come up with.

With that said, thank you very much for spearheading this effort! It is something that will help elevate not only the codebase but the experience others have when they develop new features for the script. I never thought this project would get as much support that it has over the years and I love and appreciate everyone’s contributions to the code.

Thank you!

[oliversalzburg]

Just FYI, I have moved the rewrite to https://github.com/kitten-science/kitten-scientists An organization is probably a good solution anyway 😃