Add vscode debugging setup using emulicious to template

.gitignore

@@ -274,3 +274,4 @@ tools/*/*.o
 tools/*/*/*.o
 tools/*/test
 
+!examples/*/.vscode

README.md

@@ -21,7 +21,7 @@ It uses [GBDK 2020](https://github.com/gbdk-2020/gbdk-2020/releases/latest) but
 - Creating a new project
   - Take the CrossZGB-template from the CrossZGB examples subfolder and build it by running `build.bat` or `make` from the `template/src` folder
   - Follow the tutorial on the [wiki](https://github.com/gbdk-2020/CrossZGB/wiki) to understand the basic concepts of the engine
-- (**Optional**) Download [***Microsoft Visual Studio Community Edition***](https://www.visualstudio.com/downloads/) or the [***Microsoft Visual Studio Code***](https://code.visualstudio.com/download/)
+- (**Optional**) Download [***Microsoft Visual Studio Community Edition***](https://www.visualstudio.com/downloads/) or [***Microsoft Visual Studio Code***](https://code.visualstudio.com/download/) and follow [the VSCode setup guide in the template readme](examples/!template/README.md).
 
 ## Examples
 See the included basic [example projects](/examples) as well as the [Made with CrossZGB](https://github.com/gbdk-2020/CrossZGB/wiki/Made-with-CrossZGB) Wiki page for source code and demonstrations of how to target multiple platforms and use other features of the engine.

examples/!template/.vscode/c_cpp_properties.json

@@ -0,0 +1,29 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/**",
+                "${workspaceFolder}/include",
+                "${env:ZGB_PATH}/include",
+                "${env:ZGB_PATH}/../../gbdk/include"
+            ],
+            "defines": [
+                "_DEBUG",
+                "UNICODE",
+                "_UNICODE",
+                "__PORT_gbz80",
+                "__TARGET_gb"
+            ],
+            "windowsSdkVersion": "8.1",
+            "compilerPath": "${env:ZGB_PATH}/../../gbdk/bin/lcc",
+            "cStandard": "c11",
+            "cppStandard": "c++17",
+            "intelliSenseMode": "${default}",
+            "browse": {
+                "limitSymbolsToIncludedHeaders": true
+            }
+        }
+    ],
+    "version": 4
+}

examples/!template/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "emulicious.emulicious-debugger",
+        "ms-vscode.cpptools",
+        "sandcastle.vscode-open"
+    ]
+}

examples/!template/.vscode/launch.json

@@ -0,0 +1,53 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "emulicious-debugger",
+            "request": "launch",
+            "name": "Debug",
+            "program": "${workspaceFolder}/obj/Debug/gb/rom.gb",
+            "port": 58870,
+            "stopOnEntry": false,
+            "additionalSrcFolders": "${env:ZGB_PATH}",
+            "emuliciousPath": "${env:EMULICIOUS_PATH}",
+            "preLaunchTask": "Debug",
+        },
+        {
+            "type": "emulicious-debugger",
+            "request": "launch",
+            "name": "DebugColor",
+            "program": "${workspaceFolder}/obj/DebugColor/gbc/rom.gbc",
+            "port": 58870,
+            "host": "localhost",
+            "stopOnEntry": false,
+            "additionalSrcFolders": "${env:ZGB_PATH}",
+            "emuliciousPath": "${env:EMULICIOUS_PATH}",
+            "preLaunchTask": "DebugColor",
+        },
+        {
+            "type": "emulicious-debugger",
+            "request": "launch",
+            "name": "Release",
+            "program": "${workspaceFolder}/obj/Release/gb/rom.gb",
+            "port": 58870,
+            "stopOnEntry": false,
+            "additionalSrcFolders": "${env:ZGB_PATH}",
+            "emuliciousPath": "${env:EMULICIOUS_PATH}",
+            "preLaunchTask": "Release",
+        },
+        {
+            "type": "emulicious-debugger",
+            "request": "launch",
+            "name": "ReleaseColor",
+            "program": "${workspaceFolder}/obj/ReleaseColor/gbc/rom.gbc",
+            "port": 58870,
+            "stopOnEntry": false,
+            "additionalSrcFolders": "${env:ZGB_PATH}",
+            "emuliciousPath": "${env:EMULICIOUS_PATH}",
+            "preLaunchTask": "ReleaseColor",
+        }
+    ]
+}

examples/!template/.vscode/settings.json

@@ -0,0 +1,67 @@
+{
+    "files.exclude": {
+        "*.bat": true,
+        "*.log": true,
+        "*.sln": true,
+        "*.vcxproj*": true,
+        "*.db": true,
+        ".gitignore": true,
+        ".vs": true
+    },
+    "files.associations": {
+        "spritemanager.h": "c",
+        "vector.h": "c",
+        "zgbmain.h": "c",
+        "math.h": "c",
+        "setautobank.h": "c",
+        "sound.h": "c",
+        "music.h": "c",
+        "gb.h": "c",
+        "zgbmain_init.h": "c",
+        "main.h": "c",
+        "scroll.h": "c",
+        "print.h": "c",
+        "string.h": "c",
+        "keys.h": "c",
+        "dialog.h": "c",
+        "dialogstrings.h": "c",
+        "stdlib.h": "c",
+        "types.h": "c",
+        "gbc_hicolor.h": "c",
+        "day.h": "c",
+        "tilesinfo.h": "c",
+        "platform.h": "c",
+        "gbdk-lib.h": "c",
+        "provides.h": "c",
+        "stdint.h": "c",
+        "incbin.h": "c",
+        "night.h": "c",
+        "sprite.h": "c",
+        "metaspriteinfo.h": "c",
+        "oammanager.h": "c",
+        "fade.h": "c",
+        "isr.h": "c",
+        "imported.h": "c",
+        "states.h": "c",
+        "ranges": "c",
+        "span": "c",
+        "vector": "c",
+        "xstring": "c",
+        "xutility": "c",
+        "customdata.h": "c",
+        "stateinit.h": "c",
+        "portal.h": "c",
+        "cstdint": "c",
+        "iosfwd": "c",
+        "playercollision.h": "c",
+        "interactable.h": "c",
+        "cgb.h": "c",
+        "sms.h": "c",
+        "sgb.h": "c",
+        "hardware.h": "c"
+    },
+    "makefile.makefilePath": "src/MakeFile",
+    "terminal.integrated.env.linux": {
+        "ZGB_PATH": "${env:ZGB_PATH}"
+    }
+}

examples/!template/.vscode/tasks.json

@@ -0,0 +1,110 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Release",
+            "type": "shell",
+            "command": "make",
+            "options": {
+                "cwd": "${workspaceFolder}/src",
+                "env": {
+                    "ZGB_PATH": "${env:ZGB_PATH}"
+                }
+            },
+            "isBackground": false,
+            "args": [
+                "BUILD_TYPE=Release"
+            ],
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "ReleaseColor",
+            "type": "shell",
+            "command": "make",
+            "options": {
+                "cwd": "${workspaceFolder}/src",
+                "env": {
+                    "ZGB_PATH": "${env:ZGB_PATH}"
+                }
+            },
+            "isBackground": false,
+            "args": [
+                "BUILD_TYPE=ReleaseColor"
+            ],
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "Debug",
+            "type": "shell",
+            "command": "make",
+            "options": {
+                "cwd": "${workspaceFolder}/src",
+                "env": {
+                    "ZGB_PATH": "${env:ZGB_PATH}"
+                }
+            },
+            "isBackground": false,
+            "args": [
+                "BUILD_TYPE=Debug"
+            ],
+            "problemMatcher": [
+                "$gcc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "DebugColor",
+            "type": "shell",
+            "command": "make",
+            "options": {
+                "cwd": "${workspaceFolder}/src",
+                "env": {
+                    "ZGB_PATH": "${env:ZGB_PATH}"
+                }
+            },
+            "isBackground": false, 
+            "args": [
+                "BUILD_TYPE=DebugColor"
+            ],
+            "problemMatcher": [
+                "$gcc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "Clean",
+            "type": "shell",
+            "command": "make",
+            "options": {
+                "cwd": "${workspaceFolder}/src",
+                "env": {
+                    "ZGB_PATH": "${env:ZGB_PATH}"
+                }
+            },
+            "isBackground": false,
+            "args": [
+                "BUILD_TYPE=${defaultBuildTask}",
+                "clean"
+            ],
+            "problemMatcher": [
+                "$gcc"
+            ]
+        }
+    ]
+}

examples/!template/README.md

@@ -1,2 +1,20 @@
 # ZGB-template
 A template for projects using ZGB, A little engine for creating games
+
+# VSCode debugging using Emulicious
+- Download CrossZGB to e.g. `~/CrossZGB`
+- Download [Emulicious](https://emulicious.net/downloads/) to e.g. `~/Emulicious.jar`
+- Install a java runtime environment (if you haven't already): `sudo apt install openjdk-21-jre`
+- Add to your `.bashrc`, replacing the example paths with yours
+```
+export ZGB_PATH=~/CrossZGB/ZGB/common
+export EMULICIOUS_PATH=~/Emulicious.jar
+```
+- Open your copy of the template in VSCode
+- Install the workspace recommended extensions:
+  - [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
+  - [Emulicious Debugger](https://marketplace.visualstudio.com/items?itemName=emulicious.emulicious-debugger)
+
+Now open the Run and Debug tab, select Debug or DebugColor, and press the play button to start debugging. Emulicious will be launched automatically and breakpoints will be hit. Enjoy!
+
+> Note if using WSL: make sure your code is in your home directory rather than shared from windows, otherwise emulicious debugging won't work.