v2.0 Proposal

[oliversalzburg]

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 7ba6b74):

• 0f54168
• 5d43646
• 0581a95
• 4064c62
• 90018e6
• 9bb7123
• 85f452a
• 937fb24
• 8f1478e

[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]

Thank you very much for the kind response.

In the current revision, most of the CSS adjustments are still disabled. Mostly because I'm trying to determine what their intended use specifically was. I feel the effects so far are mostly positive, as the KS UI integrates well with all the different themes. That said, everything is still very much a work in progress.

I very much agree with your view on the development experience and I hope I've already made progress very much in line with what you mentioned. There is an overview in the development guidance.

Review of any parts of the code base would be very much appreciated. I also hang out on the KG Discord, mostly in the #scripts-code channel. In case that helps with conversations.

[oliversalzburg]

While I still wasn't able to include the commits mentioned above, I have picked up work again in the past weeks and was even able to fix some long-standing issues in the script.

I've also considerably worked on the CI part of things to be able to continuously roll out nightly builds and development builds on every commit.

Overall, the quality of the script is improving and I have entirely moved over to using the rewrite for my personal KG gaming. I started a fresh game to put the script through a proper test and fix all issues along the way.

[cameroncondry]

I am once again in love with this rewrite. The system is well documented, very tidy, and well organized. My only wish would be to have the free time to pick this up and dig in.

I started many fresh games when running the script through the paces, but there gets a point where it just takes too long to get to a certain point in the game. I like the idea for the fixtures to solve this and let us just load to whichever point in the game that is needed.

Keep up the good work and have a blast working on the rewrite. I don't know how I got so lucky to still have this project drumming up interest and being actively used after this long. The initial commit was 7 years ago...

[oliversalzburg]

Thanks for the kind words. I really agree that it's tough to have all the different stages on your radar. So far, I've fixed a couple of issues in the early game (BulkManager had several issues that must have been merged some time in the past), but I know time skipping and leviathan trades had some issues with them.

There is no shortage of plans, that's for sure :D I hope I can live up to them

[oliversalzburg]

@cameroncondry Unless you oppose, I would like to reintegrate v2 into this repo soon. This repo has higher visibility and working in forks is slightly less fancy than working in "real" repositories. Would you be okay in giving me admin access to the repo? We could also move the repo into an organization if you'd rather detach it a bit from your personal account at this point. Feel free to reach out via email if necessary :)

[oliversalzburg]

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