Skip to content

Development Guide

Question

Please help us translate KS, either by contributing missing translations or reviewing the existing entries.

Introduction

The script is written in TypeScript. The JS userscript itself is not intended to be edited. Changes need to be made in the userscript source code and then be compiled into the actual userscript.

The project is set up to be used with Visual Studio Code. While other editors will work fine, some integrations have been prepared to make the development process easier.

Prerequisites

The development environment is expected to be a POSIX-compliant system. On Windows, WSL will do fine.

You will need NodeJS to be able to work with the project. The project uses yarn as a package and project manager, which is usually integrated with recent NodeJS versions.

Additionally, you will need to have Podman available, to use the container-based Kittens Game development server. If you do not have Podman, you can still build a release version of the script and drop that into your userscript manager. You can also use Docker, or other container engines, but the existing tooling is built around podman.

General Development

Whenever you want to see the result of your changes, use:

yarn kitten-scientists:build

This will build a fresh version of the userscript. If you are running a development container, this build output will also be used the next time you refresh the page.

Development with Kittens Game Container

The development container provides a version of Kittens Game that already a Kitten Scientists version injected into it, based on your local development state.

When the container is built, it downloads the latest version of the game from https://github.com/nuclear-unicorn/kittensgame.

  1. Manual Refresh (recommended)

    Build the development container and start it.

    yarn devcontainer:run
    

    The script prints the URL where you can now play the game with KS installed.

    You will need to manually reload the page after each build to get the latest changes in the browser.

  2. Watcher (experimental)

    Start a watcher to continuously rebuild KS when you make code changes.

    yarn kitten-scientists:watch
    

    Danger

    Sadly, this behavior is known to produce broken output files. Use at your own risk and switch to manual builds as necessary.

If you ever want to rebuild the container from scratch, for example, to pull in the latest source code of KG again, run:

yarn devcontainer:rebuild

Kittens Game Branch

You can run the development container on another branch of Kittens Game by providing the branch name to the devcontainer commands, like so:

yarn devcontainer:run dev/alpha

Development without Container

To develop without containers, you can build a development version of the userscript with full debugging information.

  1. Run the build script.

    yarn kitten-scientists:preview
    

    The userscript is placed in the packages/kitten-scientists/output directory.

Type-Checking

To fill the Problems panel in VS Code with all current, type-related errors, run the typecheck:all npm task in VS Code.

Commit Standards

KS development follows the Conventional Commits specification for commit messages.

Whenever possible, use one of the established scopes:

Tab related:

  • bonfire
  • religion
  • science
  • space
  • time
  • trade
  • village
  • workshop

Internals related:

  • api

    Relates to the global kittenScientists API.

  • build

    Relates to the process of producing one of the KS release fragment.

  • container

    Relates to the KS development container.

  • core

    Relates to central behavior of KS. Also includes state management.

  • filters

    Relates to the log filters of KS.

  • i18n

    Relates to translations of KS.

  • settings

    Relates to changes to the settings system.

  • ui

    Relates to the KS user interface.

Pull Requests

When you open a pull request, make sure that you squash your commits into a single one, unless individual commits are substantial enough that they should be preserved as-is. Just make sure that all commits follow the commit standards mentioned above.

Releases

Building a Release Version of the Userscript

Run the script to build the release:

yarn kitten-scientists:release

Releasing a New Version

  1. Build a preview of the script:

    yarn kitten-scientists:preview
    
  2. Load the built preview into a userscript manager in Chrome and perform a quick, manual test.

    1. Does the script load at all?
    2. Are settings restored to expectation?
    3. Are settings saved when they are changed?
  3. Create a tag for this version:

    git tag v2.0.0-beta.9
    
  4. Push the tag:

    git push --tags
    
  5. Raise the version number in packages/kitten-scientists/package.json to a higher version that will be in development next!

  6. Make sure to also update the README.md to point the bookmarklet to the new script.

  7. Make sure to also update the packages/documentation/installation.md to point to the latest version number.

  8. Make sure to also update the .github/bug_report.yml to mention the latest version number.

Note

Don't forget to publish the drafted release on GitHub!