Fix old test, filesystem, and readme

Author: masonova1

README.md

@@ -1,54 +1,110 @@
 # TinyCircuits-Tiny-Game-Engine
-This is a game engine for embedded devices that can run MicroPython.
 
-# Building on Linux
+This is a 2D/3D game engine for MicroPython. Core engine features are written in C and integrated into MicroPython as external C modules. The engine API is exposed through Python modules.
+
+<p align="center">
+  <img width="65%" src="images/games.png">
+</p>
+
+### **Engine Features**:
+* Node API with hierarchy format (parent/child) to render rectangles, circles, lines, text, GUI buttons, sprites, and 3D meshes.
+* All nodes can be rotated and scaled
+* Resource API for loading and holding data like 1/4/8/16-bit bitmap textures, .wav sound files, RTTTL ringtone tracks, fonts, and 2D/3D noise
+* Basic button API
+* Audio API for 4 audio channels to play .wav, RTTTL, or tones
+* Basic 2D physics engine with rotated rectangle and circle colliders exposed as nodes
+* Math API for `Vector2` and `Vector3` types
+* Tween/animation API to animate attributes of nodes
+* Saves API for reading and writing certain common types of data
+* Time API for utilizing hardware real-time-clock (RTC) for keeping persistent time across device power-downs
+* Link API for connecting two devices together to make local multiplayer games
+
+You can also read the engine documentation, visit the arcade to download games, or make your own games using the Code Editor Web App:
+* [Engine Documentation](https://color.thumby.us/doc/landing.html)
+* [Arcade](https://color.thumby.us/code/arcade)
+* [MicroPython Code Editor](https://color.thumby.us/code/)
+
+
+# Platforms
+The engine can run on most platforms that run [MicroPython](https://github.com/TinyCircuits/micropython/tree/engine). However, some drivers may need to be implemented for buttons, screen, and audio.
+
+The engine has been tested on and ported to the following platforms:
+* Linux/Unix
+* RP2350 with 16MiB flash
+* Webassembly
+
+
+# Building on Linux for RP2350
+1. Update package list: `sudo apt update`
+2. Install build chain dependencies (https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf#page=33): `sudo apt install git python3 cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential g++ libstdc++-arm-none-eabi-newlib`
+3. Clone TinyCircuits MicroPython: `git https://github.com/TinyCircuits/micropython.git mp-thumby`
+4. `cd` into MicroPython: `cd mp-thumby`
+5. Checkout engine branch: `git checkout engine`
+6. Init the engine submodule: `git submodule update --init --recursive`
+7. Setup cross compiler:
+   1. cd `mpy-cross` (folder is inside `mp-thumby`)
+   2. `make -j8`
+8. Go back to MicroPython root folder: `cd ..`
+9. Setup `rp2` port:
+   1. `cd ports/rp2`
+   2. `make submodules`
+   3. `make clean`
+10. Go back to MicroPython root folder: `cd ../..`
+11. Go into engine folder: `cd TinyCircuits-Tiny-Game-Engine`
+12. Run the custom Python build and upload script: `python3 build_and_upload.py`
+
+(NOTE: you may need to install `pyserial`: `python3 -m pip install pyserial` and the .uf2 will be output to `mp-thumby/ports/rp2/build-THUMBY_COLOR/firmware.uf2` once you see the message `Finding drive letter...`)
+
+# Building on Linux for Linux
 These instructions assume that you are cloning MicroPython from the TinyCircuits Fork that has been pre-modified
 1. Install SDL2: `sudo apt install libsdl2-dev`
-2. Install build tools: `sudo apt install build-essential`
-3. Clone TinyCircuits MicroPython: `git clone https://github.com/TinyCircuits/micropython.git mp-thumby`
-4. `cd` into MicroPython: `cd mp-thumby`
-5. Checkout engine branch: `git checkout engine-1.23.0`
-6. Clone latest engine module code with `lib` submodules: `git clone --recurse-submodules https://github.com/TinyCircuits/TinyCircuits-Tiny-Game-Engine.git`
-7. Setup UNIX port:
+2. Install FFI: `sudo apt install libffi-dev`
+3. Install build tools: `sudo apt install build-essential`
+4. Clone TinyCircuits MicroPython: `git clone https://github.com/TinyCircuits/micropython.git mp-thumby`
+5. `cd` into MicroPython: `cd mp-thumby`
+6. Checkout engine branch: `git checkout engine`
+7. Init the engine submodule: `git submodule update --init --recursive`
+8. Setup UNIX port:
    1. `cd ports/unix`
    2. `make submodules`
-8. `cd` to engine file system to build and run MicroPython and the engine
+9. `cd` to engine file system to build and run MicroPython and the engine
    1. `cd`: `cd ../../TinyCircuits-Tiny-Game-Engine/filesystem`
    2. build: `(cd ../../ports/unix && make -j8 USER_C_MODULES=../../TinyCircuits-Tiny-Game-Engine DEBUG=1)`
-   3. run: `../micropython_loop ../../ports/unix/build-standard/micropython -X heapsize=532480 main.py`
+   3. run: `../micropython_loop ../../ports/unix/build-standard/micropython -X heapsize=2617152 main.py`
 
 Use `(cd ../../ports/unix && make clean)` to make clean if needed
 
-# Building on Linux, from Scratch
-These instructions assume that you are cloning MicroPython from the official MicroPython repository and not the TinyCircuits Fork
+# Building and Running On Linux Quickly 
+If you followed the one of two methods to setup everythign above, you can run the following from `micropython/TinyCircuits-Tiny-Game-Engine/filesystem` to build and run a MicroPython script on Linux quickly:
 
-1. Install SDL2: `sudo apt install libsdl2-dev`
-2. Install build tools: `sudo apt install build-essential`
-3. Clone MicroPython: `git clone https://github.com/micropython/micropython.git`
-4. `cd` into MicroPython: `cd micropython`
-5. Reset to MicroPython version 1.23.0: `git reset --hard a61c446`
-6. Clone latest engine module code with `lib` submodules: `git clone --recurse-submodules https://github.com/TinyCircuits/TinyCircuits-Tiny-Game-Engine.git`
-7. Setup UNIX port:
-   1. `cd ports/unix`
-   2. `make submodules`
-8. Inside `micropython/ports/unix/variants/mpconfigvariant_common.h` do:
-   1. Change `#define MICROPY_FLOAT_IMPL (MICROPY_FLOAT_IMPL_DOUBLE)` -> `#define MICROPY_FLOAT_IMPL (MICROPY_FLOAT_IMPL_FLOAT)`
-   2. Change `#define MICROPY_LONGINT_IMPL (MICROPY_LONGINT_IMPL_MPZ)` -> `#define MICROPY_LONGINT_IMPL (MICROPY_LONGINT_IMPL_LONGLONG)`
-   3. Add `#define MICROPY_TRACKED_ALLOC (1)` anywhere
-9. UGLY: inside `micropython/tools/mpy-tool.py`
-   1. Change line 1784 to `default="longlong"` (don't know where this tool is used and how to pass it a different value, will just set it for now)
-10. `cd` to filesystem root: `cd micropython/TinyCircuits-Tiny-Game-Engine/filesystem`
-11. Build MicroPython UNIX port: `(cd ../../ports/unix && make -j8 USER_C_MODULES=../../TinyCircuits-Tiny-Game-Engine DEBUG=1)`
-12. Run MicroPython port: `../micropython_loop ../../ports/unix/build-standard/micropython -X heapsize=532480 main.py`
+`(cd ../../ports/unix && make -j8 DEBUG=1 USER_C_MODULES=../../TinyCircuits-Tiny-Game-Engine) && (../../ports/unix/build-standard/micropython main.py)`
 
-Use `(cd ../../ports/unix && make clean)` to make clean if needed
+# Diagnosing HARD_FAULT
+If a hard fault blue screen occurs on the device, it will also usually occur in the Linux build too. It likely still won't be easy to solve, but you can see exactly where in MicroPython or the engine C code where the fault occurs using `gdb`. Using Linux is easier, but `gdb` can be used with the device as well but it is harder to setup.
+
+Refer to the above section where MicroPython and the engine are built on Linux for Linux. Make sure the `DEBUG=1` flag is added to the `make` command as shown above and then run MicroPython using `gdb` like so:
+1. Navigate filesystem: `cd TinyCircuits-Tiny-Game-Engine/filesystem`
+2. Build and run with `gdb`: `(cd ../../ports/unix && make -j8 DEBUG=1 USER_C_MODULES=../../TinyCircuits-Tiny-Game-Engine) && (gdb ../../ports/unix/build-standard/micropython main.py)`
+3. In the `gdb` prompt, execute `run main.py` and do it again after launching game when the window closes
+4. Play the game until it crashes and see the line in the C code where the fault occurred. In the `gdb` prompt, execute `bt` to see a stacktrace for the steps up to this point
+
+The above steps will get you started, you will likely need to understand the code and use other `gdb` tools to investigate the issue. For example, to see the value of a memory address, use `x <hex address>` in the `gdb` prompt.
+
+# Building on Linux for WebAssembly
+1. Follow instructions here https://emscripten.org/docs/getting_started/downloads.html and finish after executing `source ./emsdk_env.sh` (will need to execute this last command in `emsdk` in every new terminal/session)
+2. `git clone https://github.com/TinyCircuits/micropython/tree/engine micropython`
+3. `cd micropython/ports/webassembly`
+4. `make -j8 USER_C_MODULES=../../TinyCircuits-Tiny-Game-Engine`
+
+# Linux and Webassembly heap size
+To mimic the hardware, the heap needs to be `520kB` SRAM + `2MiB` of FLASH scratch = `520*1000 + 2*1024*1024 = 2617152`
 
 # Updating MicroPython version
 Make sure to check that the copied structures in src/utility/engine_mp.h are still the same in the version of MicroPython you're updating to. Some structures are not exposed so they had to be copied to where the engine can use them.
 
 # How UF2s are made
 1. Download and compile https://github.com/raspberrypi/picotool (requires pico-sdk be installed in default known location or pass `-DPICO_SDK_PATH=` to `cmake`)
-2. Upload a firmware and all files that should be included to Thumby Color
-3. Connect Thumby Color to computer with picotool installed in BOOTSEL mode (turn off, press and hold down DPAD direction, turn back on)
-4. Run: `sudo ./picotool save -r 0x10000000 0x11000000 thumby_color_dev_kit_full_image_08_20_2024.bin` (saves from `XIP_BASE` to `16MiB`s after to bin file)
-5. Run: `sudo ./picotool uf2 convert thumby_color_dev_kit_full_image_08_20_2024.bin thumby_color_dev_kit_full_image_08_20_2024.uf2`
+2. Upload a firmware and all files that should be included to Thumby Color (run the `collect_files_for_image.py` and copy files using Thonny from the `production_files/tree` folder)
+3. Connect Thumby Color to computer with picotool installed in and the device in BOOTSEL mode (turn off, press and hold down DPAD direction, turn back on)
+4. Run: `sudo ./picotool save -r 0x10000000 0x11000000 thumby_color_full_image_00_00_0000.bin` (saves from `XIP_BASE` to `16MiB`s after to bin file)
+5. Run: `sudo ./picotool uf2 convert thumby_color_full_image_00_00_0000.bin thumby_color_full_image_00_00_0000.uf2`

doc/landing.html

@@ -22,43 +22,5 @@ <h3>Importable Modules:</h3>
         <a href="build/engine_save.html">engine_save</a><br>
         <a href="build/engine_time.html">engine_time</a><br>
         <a href="build/engine_link.html">engine_link</a><br>
-
-        <hr>
-
-        <h3>Launcher Folder Structure:</h3>
-        Games have to be in subdirectories of <code>/Games</code>. They can be organised in any directory structure.
-
-        <h4>Minimal example:</h4>
-            <pre>
-─ /Games/mygame
-  ├─ main.py
-</pre>
-            This type of format will show up with a question mark as the icon and the folder name as the game name.
-
-        <h4>Minimal example with icon:</h4>
-            <pre>
-─ /Games/mygame
-  ├─ main.py
-  ├─ icon.bmp
-</pre>
-            Instead of a question mark, the game will show up with <code>icon.bmp</code> as the icon. For now, the only supported resolution is 64x64.
-
-        <h4>Full example:</h4>
-            <pre>
-─ /Games/mygame
-  ├─ manifest.ini
-  ├─ game.py
-  ├─ game_icon.bmp
-</pre>
-            In this example, the names of all the assets are configured in <code>manifest.ini</code>. In the manifest the following lines can be present:
-            <pre>
-name = Any Name I Want
-version = 0.3
-main = game.py
-icon = game_icon.bmp
-</pre>
-            This format is recommended, and at least the version entry should appear in the manifest. The other entries are optional, defaulting
-            to directory name, main.py and icon.bmp.
-
     </body>
 </html>

filesystem/Games/TestGames/Collision/main.py

@@ -81,8 +81,8 @@ def tick(self, dt):
 
     def on_collide(self, contact):
         self.count = self.count + 1
-        # print("Collision!", self.count)
-        # Circle2DNode(position=contact.position, radius=1)
+        print("Collision!", self.count)
+        Circle2DNode(position=contact.position, radius=1)
 
 camera = CameraNode()
 

filesystem/Games/TestGames/Font/main.py

@@ -1,18 +1,25 @@
 import engine_main
-
+import engine
 from engine_resources import FontResource
-from engine_nodes import Text2DNode
+from engine_nodes import Text2DNode, CameraNode
 from engine_math import Vector2
 
-roboto_font = FontResource("9pt-roboto-font.bmp")
+roboto_font = FontResource("/Games/TestGames/Font/Portfolio6x8-1bit.bmp")
+# roboto_font = FontResource("/Games/TestGames/Font/9pt-roboto-font.bmp")
 
 class MessageSprite(Text2DNode):
     def __init__(self):
         super().__init__(self)
-        self.text = "testing"
+        self.text = "Hello"
         self.layer = 7
         self.position = Vector2(0, 0)
         self.font = roboto_font
         self.opacity = 1.0
+        self.scale.x = 2
+        self.scale.y = 2
+
+current_msg = MessageSprite()
+
+cam = CameraNode()
 
-current_msg = MessageSprite()
+engine.start()