Merge branch 'coding-horror:main' into main

HOW_TO_RUN_THE_GAMES.md

@@ -23,16 +23,19 @@ Alternatively, for non-dotnet compatible translations, you will need [Visual Stu
 
 ## java
 
+**TIP:** You can build all the java and kotlin games at once
+using the instructions in the [buildJvm directory](buildJvm/README.md)
+
 The Java translations can be run via the command line or from an IDE such as [Eclipse](https://www.eclipse.org/downloads/packages/release/kepler/sr1/eclipse-ide-java-developers) or [IntelliJ](https://www.jetbrains.com/idea/)
 
 To run from the command line, you will need a Java SDK (eg. [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) or [Open JDK](https://openjdk.java.net/)).
 
 1. Navigate to the corresponding directory.
 1. Compile the program with `javac`:
-    * eg. `javac AceyDuceyGame.java`
+   * eg. `javac AceyDuceyGame.java`
 1. Run the compiled program with `java`:
-    * eg. `java AceyDuceyGame`
+   * eg. `java AceyDuceyGame`
-    
+
 or if you are **using JDK11 or later** you can now execute a self contained java file that has a main method directly with `java <filename>.java`.
 
 ## javascript
@@ -41,6 +44,11 @@ The javascript examples can be run from within your web browser:
 
 1. Simply open the corresponding `.html` file from your web browser.
 
+## kotlin
+
+Use the directions in [buildJvm](buildJvm/README.md) to build for kotlin. You can also use those directions to
+build java games.
+
 ## pascal
 
 The pascal examples can be run using [Free Pascal](https://www.freepascal.org/). Additionally, `.lsi` project files can be opened with the [Lazarus Project IDE](https://www.lazarus-ide.org/).
@@ -48,7 +56,7 @@ The pascal examples can be run using [Free Pascal](https://www.freepascal.org/).
 The pascal examples include both *simple* (single-file) and *object-oriented* (in the `/object-pascal`directories) examples.
 
 1. You can compile the program from the command line with the `fpc` command.
-    * eg. `fpc amazing.pas`
+   * eg. `fpc amazing.pas`
 1. The output is an executable file that can be run directly.
 
 ## perl
@@ -57,7 +65,7 @@ The perl translations can be run using a perl interpreter (a copy can be downloa
 
 1. From the command-line, navigate to the corresponding directory.
 1. Invoke with the `perl` command.
-    * eg. `perl aceyducey.pl`
+   * eg. `perl aceyducey.pl`
 
 ## python
 
@@ -65,8 +73,8 @@ The python translations can be run from the command line by using the `py` inter
 
 1. From the command-line, navigate to the corresponding directory.
 1. Invoke with the `py` or `python` interpreter (depending on your python version).
-    * eg. `py acey_ducey_oo.py`
+   * eg. `py acey_ducey_oo.py`
-    * eg. `python aceyducey.py`
+   * eg. `python aceyducey.py`
 
 **Note**
 
@@ -80,7 +88,7 @@ If you don't already have a ruby interpreter, you can download it from the [ruby
 
 1. From the command-line, navigate to the corresponding directory.
 1. Invoke with the `ruby` tool.
-    * eg. `ruby aceyducey.rb`
+   * eg. `ruby aceyducey.rb`
 
 ## vbnet
 

buildJvm/README.md

@@ -1,25 +1,56 @@
 # JVM gradle scripts
 
 ## Quickstart
+You will need to install openjdk 17, because some games use advanced Java features.
+We should be using version 17 anyway, because anything less than 17 is deprecated.
 
 Build all the games:
-
+```shell
-    cd buildJvm
+ cd buildJvm
-    ./gradlew -q assemble installDist distributeBin distributeLib
+ ./gradlew -q assemble installDist distributeBin distributeLib
+```
 
 Then, run a game
 
 ### Mac or linux:
-    
+```shell
-    build/distrib/bin/build_53_King_kotlin
+build/distrib/bin/build_53_King_kotlin
-
+```
 ### Windows
 [not tested yet]
 
-    build\distrib\bin\build_53_King_kotlin.bat
+```shell
+build\distrib\bin\build_53_King_kotlin.bat
+```
+
+---
+## Using an IDE to work on JVM games
+
+You can open the entire Basic Computer Games project in an IDE, with any IDE capable
+of importing from a gradle project.
+
+### IntelliJ / Android Studio
+
+1. (Optional) If you want to make changes, or contribute a new kotlin or java version
+of one of the games, use [github "fork"](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
+to create your own editable fork of the project.
+2. Check out the code using `File` -> `New` -> `Project from Version Control`
+   1. Enter the URL of the project. For the main project this will be `https://github.com/coding-horror/basic-computer-games.git`, for your
+own fork this will be `https://github.com/YOURNAMEHERE/basic-computer-games.git`
+   2. Choose a directory for the clone to live in
+3. Click `Clone`
+
+The project will open, and eventually you will get a little alert box in the bottom right corner saying "Gradle build script found". 
+
+Click the "Load" link in the alert box, to load the gradle project.
+
+You should see all the games appear on the left side of the screen. If you have loaded
+your own fork, you can modify, commit and push your changes to github.
+
+If you are using the main `coding-horror` branch, you can still make and run your own changes.  If
+your git skills are up to the task, you might even fork the project and change your
+local clone to point to your new forked project.
 
-You will need to install openjdk 17, because some games use advanced Java features. 
-We should be using version 17 anyway, because anything less than 17 is deprecated.
 
 ---
 ## Adding a new game
@@ -34,9 +65,10 @@ there is some special requirement.
 directory for the java or kotlin file, and the class that contains the `main` method.
 
 The `build.gradle` file will normally be identical to this:
-
+```groovy
     plugins {
         id 'application'
+        // id 'org.jetbrains.kotlin.jvm' // UNCOMMENT for kotlin projects
     }
     
     sourceSets {
@@ -54,6 +86,7 @@ The `build.gradle` file will normally be identical to this:
     application {
         mainClass = gameMain
     }
+```
 
 And the `gradle.properties` file should look like this: