add Map Editor

Author: mattbruv

.github/workflows/build.yaml

@@ -24,6 +24,15 @@ jobs:
           python setup.py
           npm install
           npm run build
+          mkdir -p dist/editor
+
+      - name: Install and Build Editor 
+        run: |
+          cd map-o-matic-v2
+          npm install
+          npm run build
+          cd ../port
+          cp -r ../map-o-matic-v2/dist/* dist/editor/
 
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@v4

.github/workflows/run-tests.yml

@@ -0,0 +1,40 @@
+name: Run Jest Tests
+
+# This workflow will run on pushes and pull requests to the main branch
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  test:
+    # Runs on the latest version of Ubuntu
+    runs-on: ubuntu-latest
+
+    # Steps to be executed
+    steps:
+      # Step 1: Checkout the code from the repository
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      # Step 2: Set up Node.js
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '22.9.0'  # Use the version your project requires
+
+      # Step 3: Install dependencies
+      - name: Install dependencies
+        run: |
+          git submodule update --init --recursive
+          cd map-o-matic-v2
+          npm install
+
+      # Step 4: Run Jest tests
+      - name: Run Jest tests
+        run: |
+          cd map-o-matic-v2
+          npm run test

.gitignore

@@ -25,4 +25,13 @@ dist-ssr
 
 assets
 .vscode
-translate-objects
+translate-objects
+
+*/*.pdf
+docs/main.pdf
+docs/engine/collision.pdf
+docs/main.pdf
+docs/engine/main.pdf
+
+*.pdf
+*.tsbuildinfo

README.md

@@ -8,6 +8,7 @@
 ### **[Play it HERE in your Browser!](https://mattbruv.github.io/ccsr)**
 
 This is a modern port of the Shockwave game series Cartoon Cartoon Summer Resort.
+It also includes Scooby Doo Hollywood Horror Part 1 and Part 2, as well as a fully featured map editor.
 
 **Cartoon Cartoon Summer Resort** is the name of a series of four episodic Adventure Games formerly hosted on Cartoon Network's official website, featuring characters from their Cartoon Cartoons original programming. The game was created and released in summer 2000 tying in to the first Big Pick. Each playable character was from one of the shorts selected that could have become a full fleged series during the promotion.
 

Documentation.md renamed to docs/Documentation.md

@@ -0,0 +1,7 @@
+# CCSR Documentation
+
+This is a (currently incomplete)
+book which serves as documentation
+of all of the niche or previously unknown intricate details about the CCSR games and their history.
+
+It is written with [Typst](https://typst.app/), and produces a PDF book.

docs/README.md

@@ -0,0 +1,106 @@
+#pagebreak()
+
+== Collision System
+
+The repetitive background music likely takes the number one spot as far as things which made the Cartoon Cartoon Summer Resort games memorable. The second place spot for most memorable feature can safely be given to the game's collision detection system.
+
+The average player has undoubtedly come across Cartoon Cartoon Summer Resort's questionable collision system after spending some time playing the game.
+The collision system often seems illogical and random, which leads to confusion and frustration among players.
+
+Normally, objects that look like you can't walk on them don't let you walk on them. For example, trees, shrubs, and buildings are examples of objects that logically should have collision,
+and most of the time this is true.
+But as you may have experienced, there are #underline([many]) examples where this is not true.
+
+Here are a few visual examples from just the first episode which are particularly egrigious. Game screenshots are shown on the left, and their corresponding collision maps are shown on the right (collision screenshots are taken from Map-o-Matic-v2, the map editor I made).
+Red areas are non-walkable and have collision, while green areas are walkable and do not have collision.
+Sorry for the readers who are red-green colorblind, as if it couldn't be confusing enough already.
+
+#grid(
+  columns: (50%, 50%),
+  row-gutter: 3%,
+
+  image("collision/bad-1.png"),
+  image("collision/bad-1-coll.png"),
+
+  image("collision/bad-2.png"),
+  image("collision/bad-2-coll.png"),
+
+  image("collision/bad-3.png"),
+  image("collision/bad-3-coll.png"),
+
+)
+
+When we look at the game screenshots on the left without considering the collision maps on the right,
+it looks totally absurd.
+The player character is climbing on the roofs of buildings, over shrubs, palm trees, and in the middle of areas that look like they should be completely out of bounds.
+
+The bounds are a lot more clear when we look at the collision maps, but it still doesn't make sense as to why those specific areas are walkable while others aren't.
+Why is there no collision in these areas?
+There are 3 simple causes which account for almost all of the broken collision detection.
+
+Despite the seemingly complicated and illogical collision consistency, the collision system is surprisingly very logical and  consistent.
+It just needs to be understood to be used effectively.
+The real problem with the collision system is that it is not very intuitive, but once you understand it, it's impossible to mess things up.
+
+
+=== The Three Causes of Broken Collision
+
+Here are the three causes of broken collision, we will go through each one by one, in the order of least complicated to most complicated. As far as I'm aware, these three causes make up the entirety of the glitchy collision in the games.
+
++ *Bad Map Connections* -- a walkable part of a map connects to an unwalkable part of a neighboring map
++ *Incorrectly Typed Objects* -- Objects are incorrectly marked as `FLOR` (walkable) instead of `WALL` (non-walkable)
++ *`FLOR` Overlap* -- Objects are ordered incorrectly in the map data.
+
+
+==== 1. Bad Map Connections
+
+This is the simplest to understand cause of bad collision.
+A bad map connection as a spot on a map which is walkable, and by walking on it and walking into a neighboring map,
+the player is panned over and glitched into a non-walkable area on the new map.
+
+Consider the following area:
+
+#grid(
+  columns: (50%, 50%),
+  column-gutter: 3%,
+  image("collision/connection-1.png"),
+  image("collision/connection-2.png")
+)
+
+In the image on the left, from episode 1,
+we can see that the bottom map has a walkable grassy space
+above the shrubs which are beside the building.
+If we were to align the player on that tile, and walk upwards,
+the player would be panned into the above map.
+The spot directly above in the top map is occupied
+by a palm tree, which has collision detection.
+This results in the player being stuck in the palm tree if he enters the map from below it.
+In cases like this, the player is almost softlocked, but can usually always escape by going in the reverse direction that he came in by returning to the previous map.
+
+Comparing the first image from Episode 1 on the left with the right image from Episode 2, we can see that the developers intentionally extended the flowers to now block that area, most likely because they recognized this issue after releasing the first game and it's simple to fix.
+
+This can be avoided by always making the tiles which border each other between maps have the same type.
+A walkable tile at the edge of one map should always
+lead to a walkable tile on the neighboring map,
+and likewise for non-walkable tiles.
+This bug happens when you walk into a non-walkable tile.
+
+
+This cause of bad collision is simple to understand, and comes down to bad map design.
+It seems like this type of issue didn't happen too often in practice.
+Here is another example which existed in Episodes 1 & 2, but the developers fixed in Episode 3:
+
+#image("collision/connection-3.png")
+#image("collision/connection-4.png")
+
+We can see that there is a grass tile which borders on a palm tree, but this was fixed in episode 3 by removing the two palm trees from the map on the right.
+Virtual deforestation!
+
+==== 2. Incorrectly Typed Objects
+
+The second reason is due to game objects having the incorrect collision type.
+This is also easy to understand.
+
+==== 3. `FLOR` Overlap
+
+

docs/engine/collision.typ

@@ -0,0 +1,13 @@
+
+
+= CCSR Engine
+
+== Director Basics
+
+=== Lingo Objects
+
+== Map Format
+
+  // gConMove = [#none, #AUTO, #push, #pull, #movex, #movey]
+
+#include "collision.typ"

docs/engine/collision/bad-1-coll.png

@@ -0,0 +1,21 @@
+
+= Cartoon Cartoon Summer Resort
+
+== Introduction 
+
+Introduction to CCSR
+
+== History
+
+https://www.reddit.com/r/programming/comments/9m18v2/fixing_a_bug_in_an_18_year_old_shockwave_game/
+
+https://news.ycombinator.com/item?id=18158674
+
+
+== Episode 1
+
+== Episode 2
+
+== Episode 3
+
+== Episode 4

docs/engine/collision/bad-1.png

@@ -0,0 +1,9 @@
+// #include "cover.typ"
+
+#set figure(gap: 1em)
+#set page(numbering: "1")
+
+#outline(indent: 2em)
+
+#include "intro/main.typ"
+#include "engine/main.typ"

docs/engine/collision/bad-2-coll.png

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

docs/engine/collision/bad-2.png

@@ -0,0 +1,30 @@
+# Map-o-Matic-v2
+
+Map-o-Matic-v2 is a fully featured map editor for games built on the Cartoon Cartoon Summer Resort engine.
+It supports exporting map data which is completely compatible with both the original Shockwave games built in Macromedia Director and my modern port of the game, as both parse the map data in the same way.
+
+![](images/screenshot.png)
+
+## Features
+* Load and explore projects for CCSR Episodes 1, 2, 3, 4, and Scooby Doo Hollywood Horror 1 & 2.
+* Create and edit projects
+* Create and edit maps
+* Create and edit map objects, game events, and collision
+* View collision maps
+* View a flowchart of game events
+* Export screenshots of the game world
+* Manage texture images
+
+## Development
+
+Contributions are welcome, and encouraged. Feel free to open a PR for a feature, improvement, or bug fix. 
+
+The map editor is built with [TypeScript](https://www.typescriptlang.org/),
+[React](https://react.dev/),
+[Mantine](https://mantine.dev/),
+[pixi.js](https://pixijs.com/) for 2D rendering, 
+and [Cytoscape.js](https://js.cytoscape.org/) for rendering the directed acyclic event graph.
+
+It makes heavy use of the [immer](https://immerjs.github.io/immer/) library to easily produce edited copies of immutable state, instead of having to use spread syntax a billion times in deeply nested objects to create copies of state.
+
+Setting up a development should be as easy as cloning this repo, and then running `npm install` and `npm run dev`.

docs/engine/collision/bad-3-coll.png

@@ -0,0 +1,28 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  { ignores: ['dist'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+    },
+  },
+)

docs/engine/collision/bad-3.png

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <link rel="icon" type="image/svg+xml" href="/favicon.ico" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Map-O-Matic v2</title>
+</head>
+
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+
+</html>

docs/engine/collision/connection-1.png

@@ -0,0 +1,7 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+export default {
+  testEnvironment: "node",
+  transform: {
+    "^.+.tsx?$": ["ts-jest",{}],
+  },
+};