Application. Coding

Table of Contents:

• Preparation
  • Initial Steps
  • Environment
• Git Flow and Pull Requests
  • 1. Fork the main repository
  • 2. Rebase your branch to the main one
  • 3. Prepare necessary assets
  • 4. Let us know that you are working on something
  • 5. Do the actual magic
  • 6. Perform tests
  • 7. Update the CHANGELOG
  • 8. Commit changes
  • 9. Squash changes
  • 10. Create PR
  • 11. Wait for a review and merge
• Coding
  • Reading and Setting Values and Variables
    • Player Stats
    • Food Inventory and Tools Inventory
    • Environment Stats
  • Displaying Messages
  • Translating Texts
    • Short Strings
    • Longer Texts
• Testing
  • Desktop
  • Web
  • Mobile

Table of contents generated with markdown-toc.

Preparation

Initial Steps

To be able to develop our game, test and contribute to this repository you need to have NodeJS installed in version 20 or higher. It doesn't matter which IDE you are using, however VS Code is recommended by us.

For smooth Git experience we recommend using Github Desktop.

If you plan to contribute or test mobile code you will need: Android Studio for Android builds and xCode for iOS build preferably with virtual devices installed.

Environment

After installing NodeJS you are ready to pull our repository. After doing so open terminal on your device (or directly in your IDE, if it supports this) and then:

cd code-{platform}
npm install

To run a game in dev mode for:

• Desktop or web: execute npm run dev command
• Mobile: execute npm run start command

And when prompted tap the corresponding key (a for Android etc.).

Git Flow and Pull Requests

After you made any change to the repository code you must use commitizen to commit your changes.

Merge commits done in other way will be automatically declined, sorry.

1. Fork the main repository

• Fork the niner-games/lost-dutchman-mine repo (click!) on GitHub
• Clone your fork to your development environment

2. Rebase your branch to the main one

So there will be no conflicts:

• DO NOT use merge utility, just rebase. We do not want "merge" commits
• They should be blocked automatically, but if changes happen to have merge commit, they will be declined
• Example terminal command to rebase from there: git fetch origin + git rebase origin/main

3. Prepare necessary assets

This is especially important if you are going to work with visual or GUI elements, with some sound or animation:

• Browse our Wiki thoroughly first, as there are already a lot of assets linked
• Play an on-line version of the original game in your browser or download DOS executable and run it in DosBox
• MAKE SURE that you capture any screenshot, screencast or animation in 4K (3840x2160p) resolution (details)

4. Let us know that you are working on something

• Find an issue corresponding to your change, feature request or bug fix and assign it to you
• If you have access to LDM project in this repo, change Status to In Progress (if you don't have then skip this)
• Drop a small comment for selected issue that you are starting your work on it and your estimation on finishing it
• DO NOT work on anything that doesn't have a matching issue. Create a new issue and wait for us to review it

5. Do the actual magic

Code your changes.

6. Perform tests

Perform all the necessary tests in as many scenarios, devices, screen resolutions as possible.

7. Update the CHANGELOG

8. Commit changes

Run npm run commit:plain command to commit your changes:

• From the list in terminal choose if your commit is carrying feature, bug-fix, refactor or optimization task etc.
• Type in title to describe short overview of your changes
• Type in description to describe all important details of your changes
• If there are any breaking changes, type them in corresponding field
• Type the ticket your change is closing:
  • For example: #22
  • Ticketless changes will be rejected
  • Changes pointing to a not existing ticket will be rejected as well

9. Squash changes

Squash your changes together and push them to your branch:

• In GitHub Desktop:
  • Choose all the commits you make while working on your branch
  • Right click with mouse and select Squash
  • Choose right title and description and confirm operation
• Example terminal command, if squashing from there: ``
• Not squashed commits will not be merged until done so

10. Create PR

Create a pull request:

• In GitHub Desktop: go to Codebase → Code tab
• in GitHub.com follow the on-screen instructions
• Choose main branch as a branch you want merge to
• Provide description add detailed text what your change introduce and how to test your code
• Provide some screenshots of animated gives, the your change carries some visual or GUI-related changes

11. Wait for a review and merge

Give us some time to review and merge your PR or provide you with a feedback, if anything is missing.

We are very, very thankful for any of your contributions. It is always an great experience to work with other developers.

But, in the same time we're code purist and git-flow maniacs. Failing at any of above steps may mean that your code might end up in /dev/null and not in this repo, sorry.

Coding

Reading and Setting Values and Variables

Player Stats

Food Inventory and Tools Inventory

Environment Stats

Reading and setting calendar, clock and thermometer.

Displaying Messages

Translating Texts

Short Strings

Technical details: Translations → Strings Translations.

To use any piece of text that can be translated (different depending on user-selected in-game language), import setText method first:

import { setText } from "../../context/language";

And then either use translation system directly:

<Subtitle text={setText('startup', '(press any key or click to continue)')} classes="white absolute top-with-small-margin no-margin left z-index-1 text-shadow" />

Or assign it to some variable for future use:

let messageText = setText('river', 'Too many items to carry!');

As described in here we are intentionally not using some magic placeholders (like riverTooManyItemsError) but a natural English text. If translation system fails (for any reason) user will at least see natural English text (instead of translation) and not some nearlyMeaninglessCamelCaseMonster.

Longer Texts

Technical details: Translations → Translations of Big Blocks of Text.

Testing

Desktop

Provided that you have environment prepared and working:

1. Run npm run dev command to start application in hot-reload dev mode and open it in your browser
2. Perform changes in source code and save them (most IDEs like VS Code, WebStorm etc. saves files automatically)
3. Press F5 to refresh changes in browser and and try to play a game. Check how it behaves etc.

If you want to test actual build instead then check the building instructions and:

1. Perform an actual build of your code.
2. Find installer file in your source folder.
3. Install the game and try to play it.

Please, make sure that you test your changes in as many screen resolutions, screen sizes, operating system versions (or virtual images) and actual devices as possible before sending us a PR.

Web

Since we are developing our game in Electron and React Native, what you see in browser during hot-reloaded development (after executing npm run dev command) is what you are actually going to get as a web version.

Since the resulting files are static HTML and CSS files, you can run production version of web version of our game anytime during development. All you need to do is to execute index.html file in any of your browsers. You don't even have to have a local server working. You execute it right from your disk.

Please, make sure that you test your changes in as many screen resolutions, screen sizes and web browsers types or version as possible before sending us a PR.

Mobile

To test your changes in mobile version, execute npm run start command.

Please, make sure that you test your changes in as many screen resolutions, screen sizes and actual devices (or device emulators) as possible before sending us a PR.