Application. Coding

Table of Contents:

• Preparation
  • Initial Steps
  • Environment
• Git Flow and Pull Requests
  • 1. Fork the main repository
  • 2. Branch main branch
  • 3. Rebase your branch to the main one
  • 4. Prepare necessary assets
  • 5. Let us know that you are working on something
  • 6. Do the actual magic
  • 7. Perform tests
  • 8. Update the CHANGELOG
  • 9. Commit changes
  • 10. Squash changes
  • 11. Push your changes
  • 12. Rebase
  • 13. Create PR
  • 14. Wait for a review and merge
  • 15. Clean up and... repeat? :)
• 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. Branch main branch

• Create a local branch based on main: git branch #ticket-number-ticket-title eg. git branch 50-detect-system-default-language
• We suggest to use full title of corresponding topic, if it is not too long, as in above example

3. Rebase your branch to the main one

Assure that there are no conflicts when you are starting your work:

• 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

4. Prepare necessary assets

If you are performing a visual change or developing a GUI-related issue for the first time, please make sure that you familiarize yourself with the Main Viewport chapter. Especially with: Base Pixel Ratio, Inconclusive Pixel Ratio and Dual-dimension System.

Here are some remarks, 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)

If you cannot capture a screenshot in 4K and did not find necessary asset in Wiki then contact @mrfatguy.

• Write a comment under given issue that you want to work over it, but you are missing this or that or
• Create a separate issue for gathering necessary assets, link it to the "main" issue and assign it to @mrfatguy

He'll be more than happy to capture necessary screenshot or get other asset for you.

5. 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

6. Do the actual magic

• Code your changes.

7. Perform tests

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

8. Update the CHANGELOG

Edit the CHANGELOG.md file to include a short info about your change:

• Insert this at the top of the file under the first heading (the version that is currently under development)
• Each line should follow the Bug/Eng #Issue Number: Title (Github User)` template. For example:

Bug #40: Fix player resizing with change of window height (MadejaMaciej)
Enh #50: Detect system default language (MadejaMaciej)

For each heading (version) The CHANGELOG must be grouped by type (Bug, Enh) and ordered by issue number (highest at the top). Make sure that you are adding your line in the correct place. It will not always be the first one.

For a very small fixes, code typos etc. changes, there is no need to update the CHANGELOG, but you must go through entire flow here and create a PR. You can make such small change in a separate commit and squash it to a single PR along with your other changes. You don't have to create a separate PR for a very small change.

9. 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

10. Squash changes

Squash your changes together:

• 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: git merge --squash
• Not squashed commits will not be merged until done so

11. Push your changes

Push your changes (in your branch) to your repo:

• Execute git push from command-line on corresponding sequence from Git Desktop or your IDE
• In certain situations you may need to use --force flag after squash

12. Rebase

• Switch to main branch and pull all changes from remote: git checkout main && git pull
• Checkout your branch again: git checkout 50-detect-system-default-language
• Rebase it: git rebase origin/main
• Resolve any possible conflicts
• Push your final changes: git push

13. Create PR

Create a pull request:

• 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
• In GitHub Desktop: go to Codebase → Code tab
• In your IDE follow the standard path

14. Wait for a review and merge

Give us some time to:

• Review and merge your PR, if everything is OK
• Or provide you with a feedback, if anything is missing

We want to track everything to not get lost in the whole thing, so we kindly ask you to follow this guide (though it might seem a bit overwhelming) for every change that you perform. Even for a very small fixes, e.g. typos.

15. Clean up and... repeat? :)

• Checkout main branch: git checkout main
• Delete local branch: git branch -D 50-detect-system-default-language
• Delete remote branch: git push origin --delete 50-detect-system-default-language

Thank you! Consider doing some more.

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.