diff --git a/readme.md b/readme.md index 58ef494..3a24c80 100644 --- a/readme.md +++ b/readme.md @@ -2,6 +2,7 @@ Features: +- ✓ i18n - ✓ lazy realtime economy - (timewarping) actions - building queue @@ -16,7 +17,7 @@ Infrastructure & DevEnv: - simple persistence (localstorage + file based) - hono local storage cache in service worker (proxy server) - git data push from service worker -- wait for TailwindCSS 4 stable release? +- wait for TailwindCSS 4 stable release? add a light theme too? #### 2.0: Combat @@ -26,21 +27,59 @@ Infrastructure & DevEnv: - action collision resolution - partially prevents timewarping (after espionage) -# Contribute +## Motivation -Start by forking publicly, as the [AGPL license](./license.md) requires you to do anyways! (Reminder: This license also forbids you to take commercial advantage from this code.) +Just around becoming an adult - that was 2008 - I've come along a little OpenSource PHP project inspiring me to [build my own browser game engine](https://ugamela-blog.pheelgood.net/2008/08/30/phlame-engine-ressourcenberechnung-fusionskraftwerkproblem-bauliste-mit-wartefunktion/). However I discovered a long learning path to reach the knowledge for quality, which I actually expect from OpenSource. After studying Computer Science and Information Technology for many years, I'm now working full-time as Software Engineer, gathering reserves to return to a life as a Student one day. Until then I can only sporadically spend my free time on Phlame/UGamela. Today it's a JavaScript/TypeScript project, I've turned away from PHP/SQL in favour of newer foundations. -Before creating a Pull-Request, please open an issue first. Keep commits small and focussed and title them starting with a capitalised verb in imperative (e.g. `Add`, `Change`, `Refactor`). +While this repo is equipped with high coding standards and great development tooling, it's also a playground for new and minimal Web Technology (e.g. Signals Polyfill, Tailwind4, Hono, @joist/di, ...), those packages may still need to mature, but maybe we can help a bit?! + +I hope you will also become inspired by Web Technologies and the Galactic Economy Domain, together we may build far beyond the ideas which ([originally](https://ugamela-blog.pheelgood.net/2008/08/21/ugamelas-geschichte/)) [inspired](https://www.owiki.de/index.php/Ugamela) this game! - Phoscur + +# Start with a fork: Contribute + +The project is under the [AGPLv3 license](./license.md), it requires forking publicly anyways! + +Before creating a Pull-Request, please open an issue first. Keep commits small, focussed and title them starting with a capitalised verb in imperative (e.g. `Add`, `Change`, `Refactor`). + +Please don't suggest to add React - if we are going to add any of the known frameworks it's SolidJS! (Let's try pure Custom Elements with Signals first, VanJS is also an option.) +See the wishlist below if you are looking for a place to start. + +# Docs + +You should be familiar with these dependencies: + +- [TypeScript Language](https://www.typescriptlang.org/docs/) +- Dependency Injection: [@joist/di](https://github.com/joist-framework/joist/tree/main/packages/di#di) +- Server: [Hono](https://hono.dev/concepts/motivation) it provides [JSX](https://hono.dev/jsx#usage), [TSX](https://tsx.is/) +- [HTMX](https://htmx.org/) (still evaluating) +- App made of [Custom Elements: Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_Components/Using_custom_elements) + - [TailwindCSS 4 Alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha) + - [Signals Polyfill](https://github.com/proposal-signals/signal-polyfill?tab=readme-ov-file#examples) + +### Tools: + +- [Vite Build](https://vitejs.dev/) +- [Vitest](https://vitest.dev/), [Playwright](https://vitest.dev/) + +## Architecture Concept: + +- [(Astro) Islands](https://docs.astro.build/en/concepts/islands/) + +Well, for realtime economy, we need a nice big island :D + +Render functional JSX (Hono) then hyrate Custom Elements from attributes. Choose as fine-grained scope to re-render: e.g refreshing the whole app is possible (for language switching), but also just changing attributes of a subsequent elements. Alternatively event data can be shared by injecting signals (see the [Zeitgeber](./blob/master/src/app/tick/zeit.element.tsx))! + +## Prerequisites: + +- Install [Node.JS](https://nodejs.org) including `npm` +- `git clone` your fork and `npm install` # Phlame Engine App - Run `npm start` to develop the app or `npx vite`, run `npx vitest` to run unit tests -- RUN `npm run build && NODE_ENV=production npm run preview` to run the server with `tsx` TODO add a rollup config for the [server build](https://blog.devgenius.io/full-stack-development-with-vite-and-hono-1b8c26f48956) -- Run `npm run cypress` to open Cypress for e2e tests +- RUN `npm run build && NODE_ENV=production npm run preview` to run the server with `tsx` (TODO add a rollup config for the [server build](https://blog.devgenius.io/full-stack-development-with-vite-and-hono-1b8c26f48956)) - Run `npm run test-engine` to develop the engine library with unit tests -Note Nx v18: Running `vitest` in watchmode through `nx` seems not to work for now, also `npm run dev-e2e` should run a dev-server whilst executing Cypress but after starting vite nothing else happens - ## Hono JSX Don't think just because there are `.tsx` files in this repo, that we have React! No it's very plain TypeScript, Hono, Custom WebComponents and HTMX - but JSX tooling is great (e.g. syntax highlighting) - maybe we only need the static parts (only functional components). And I haven't even added VanJS yet! @@ -52,27 +91,25 @@ Don't think just because there are `.tsx` files in this repo, that we have React - not even van vanjs yet, just pure custom web components - Signals (Draft Polyfill) - used with `@joist/di` as Zeitgeber emitting time units / game ticks -- css counter transitions with css --vars (which don't work yet in Firefox) ### POC (Tailwind 4) Learnings: - the new alpha is nice and simplistic, but not beginner friendly, as it's ecosystem and dark mode are not ready - when first using a new generated utility class, live reload does not catch it and one needs to manually refresh again -- do we need `nx`? I'm not sure if it's really a help, it's been quite annoying (neither serving cypress nor vite correctly) +- css counter transitions with css --vars (which don't work yet in Firefox) #### Wishlist -- Decide between Playwright & Cypress, we don't need both -- Drop Nx (what do we actually need it for? or do we want Analog/Angular?) -- Component Tests, Playground for different Resource ReCalculation Strategies -- Check out SolidJS or/while staying true to vanilla? -- JS Decorators, JS private accessor properties (seem to be a bit too new and clashing with bundlers/TS) -- Drop typescript (build for app, what about the engine?) -- Try Bun again - - Zeitleiste (draggable Zeitgeber Tick/Time Debugger) - Session Switcher Input or Dropdown + - e2e tests with Playwright +- Try Bun again +- Decide between Playwright & Cypress, we don't need both (dropped Cypress ✓) +- ✓ Drop Nx (what do we actually need it for? or do we want Analog/Angular?) +- Check out SolidJS or/while staying true to vanilla? +- Component Tests, Playground for different Resource ReCalculation Strategies +- Drop typescript (build for app, what about the engine?) ## Early (first Easter) POC 2021: