Merge pull request 'add engine option argument' (#3) from add-setup-manual into develop

Reviewed-on: #3

docs/faqs/01-engine.md

@@ -2,4 +2,198 @@
 sidebar_position: 1
 ---
 
-# Engine
+# Cocos Creator vs PixiJS
+
+We've been working with **Cocos Creator** for a long time and have recently started exploring **PixiJS**. After gaining experience with both frameworks, we strongly recommend continuing with **Cocos Creator** as our primary game engine, based on the following points.
+
+---
+
+## Full-Featured Engine vs Rendering-Only Framework
+
+![Cocos](./img/cocos-icon.png)
+
+Cocos Creator offers a complete, feature-rich environment that significantly **reduces development overhead** and **accelerates production timelines**.
+
+It comes with a **visual editor**, **built-in animation tools**, **component-based architecture**, and **robust cross-platform support**, making it ideal for both web and native deployment.
+
+![Pixi](./img/pixi-logo.png)
+
+PixiJS, on the other hand, is a lightweight, high-performance **rendering engine**. While it's excellent for raw rendering, it lacks out-of-the-box support for essential features like UI systems, animation tools, and scene management. These must be built or integrated separately, adding **unnecessary overhead**, **longer development time**, and **reduced team efficiency**.
+
+---
+
+## Cocos Creator Meets All the Goals PixiJS Aims to Solve
+
+PixiJS is often considered for the following reasons:
+
+- Creating a multi-layer framework for base games, slot games, and other genres.
+- Adopting newer technologies like WebGPU and asset compression.
+- Gaining full control over the game framework.
+- Offering an easy-to-use, lightweight, and high-performance environment for the web.
+
+**Cocos Creator already addresses all of these goals:**
+
+- We’ve successfully used Cocos for multiple game genres (2D & 3D), including hundreds of slot games with diverse UIs and features.
+- Cocos provides **built-in asset compression** and broad format support:
+  - **Audio**: `.wav`, `.mp3`, `.ogg`
+  - **Textures**: `.jpg`, `.png`, `.webp`, `.pkm`, `.pvrtc`
+- **WebGPU support** has been available since version 3.6.2 (released ~2.5 years ago). Enabling it requires just a toggle in the build settings.
+- While full control over the engine isn't usually necessary, Cocos Creator is **open-source**. We've already leveraged this by customizing the engine to power our slot games.
+- Its Unity-inspired design makes it **extremely intuitive**, especially compared to lower-level frameworks like PixiJS.
+
+Even though PixiJS may have an edge in raw performance, we've **never hit performance limits** in Cocos Creator that would require switching to PixiJS.
+
+---
+
+## Publishers Are Choosing Cocos Creator Over PixiJS
+
+Across the industry, publishers use a wide variety of engines: Cocos Creator, PixiJS, Phaser, Cocos2dJS, and various custom JavaScript/HTML5 frameworks.
+
+Among these, **Cocos Creator stands out as the dominant choice**.
+
+### Top 10 Publishers on Juad – Engine Usage:
+
+| Publisher         | Engine                     | Version(s)                         |
+|------------------|----------------------------|------------------------------------|
+| ![Joker](./img/joker.png)         | Cocos Creator              | 2.4.4 / 2.4.10 / 3.8.2             |
+| ![Pragmatic](./img/pragmatic.png) | PixiJS                     | 3.0.2                              |
+| ![PgSoft](./img/pgsoft.png)       | Cocos Creator              | Custom                             |
+| ![Hot Dog](./img/hot-dog.png)     | Cocos Creator              | 2.4.9                              |
+| ![Ambslot](./img/ambslot.png)     | Cocos Creator              | 2.4.9                              |
+| ![NextSpin](./img/nextspin.png)   | Cocos Creator / PixiJS     | 2.4.5 / 6.3.2                      |
+| ![GiocoPlus](./img/giocoplus.png) | Cocos Creator              | 2.4.5                              |
+| ![Fa Chai](./img/fa-chai.png)     | Cocos Creator              | 2.4.12                             |
+| ![Goldy](./img/goldy.png)         | Cocos2dJS                  | 3.17                               |
+| ![FunkyGame](./img/funky-game.png)| Cocos Creator / React-PixiJS| 3.8.2 / 16.13.1-7.1.1             |
+| ![Rich88](./img/rich88.png)       | Cocos Creator              | 2.0.9                              |
+
+:::info
+- Latest PixiJS version: **8.8**  
+- Pragmatic is still using **PixiJS 3.0.2**, released over **10 years ago**  
+- Latest Cocos Creator versions: **2.4.15** and **3.8.6**
+:::
+
+---
+
+## We're Deep Into Cocos Creator
+
+Our current projects rely heavily on Cocos Creator. Our **core logic**, **templates**, **documentation**, and **workflow** are all designed around it. 
+
+Switching to PixiJS would require:
+- Building an entirely new framework.
+- Retraining our developers.
+- Creating new tools and processes.
+- Managing a split tech stack between Cocos and PixiJS teams.
+
+The cost and complexity of such a transition far outweigh the potential benefits.
+
+---
+
+## Technical Struggles With PixiJS
+
+While evaluating PixiJS (v8.8), we encountered several **critical limitations and technical issues**:
+
+### ❌ Unsupported Particle Plugin
+- The most popular particle emitter plugin became incompatible with Pixi v8.
+- The original maintainer abandoned the project.
+- It was only revived later by a community fork, which may still have bugs.
+
+🔗 [Issue #211 – pixijs-userland/particle-emitter](https://github.com/pixijs-userland/particle-emitter/issues/211)
+
+---
+
+### ❌ Container Auto-Size Issues
+- `Container` components automatically resize based on their children.
+- This behavior makes it difficult to implement fixed-size layouts.
+- Layout solutions are fragmented across multiple plugins.
+
+🔗 [Issue #7 – pixijs/layout](https://github.com/pixijs/layout/issues/7)
+
+---
+
+### ❌ No RichText Support
+- No built-in rich text support.
+- `HTMLText` doesn't support the `<img>` tag or texture atlas integration.
+- We can't render UI like this without heavy customization:
+
+![Rich Text](./img/rich-text.png)
+
+---
+
+### ❌ No Built-In Text Shrinking
+- Overflow mode for text shrinking is not supported.
+- Current vs expected output:
+
+| Current                                | Expected                              |
+|----------------------------------------|----------------------------------------|
+| ![Text Output](./img/text-shrink-output.png) | ![Text Expected](./img/text-shrink-expect.png) |
+
+---
+
+### ❌ Missing ScrollBar in ScrollBox
+- The `ScrollBox` component lacks built-in scrollbar rendering.
+- We had to manually modify its source to add this feature.
+
+![Scrollbar](./img/scrollbar.png)
+
+---
+
+### ❌ Asset Cache Key Conflict
+- Pixi uses asset names (not unique IDs) as cache keys.
+- Duplicate names (e.g. `btn-start.png`) cause conflicts and unexpected behavior during asset loading.
+
+---
+
+## Wasted Effort on Contributing to PixiJS
+
+Each technical issue required deep debugging, community searching, and sometimes direct contributions to the PixiJS GitHub repository.
+
+While we’re happy to contribute, this **slowed down our internal development** and shifted effort away from our product.
+
+### Some of Our Contributions:
+
+- **Invisible Graphics Not Updating**
+  - Severity: CRITICAL
+  - Status: NOT FIXED  
+  - 🔗 [Issue #11294](https://github.com/pixijs/pixijs/issues/11294)  
+  - Contributor: *Phu Lai*
+
+  ![11294](./img/bug-report-1.png)
+
+---
+
+- **Font Family Cache Bug**
+  - Severity: MINOR
+  - Status: FIXED in v8.6.5  
+  - 🔗 [Pull Request #11151](https://github.com/pixijs/pixijs/pull/11151)  
+  - Contributor: *Trung Le*
+
+  ![11151](./img/bug-report-2.png)
+
+---
+
+- **AssetPack Power of Two Issue**
+  - Severity: MINOR
+  - Status: FIXED in `assetpack` v1.3.0  
+  - 🔗 [Pull Request #105](https://github.com/pixijs/assetpack/pull/105)  
+  - Contributor: *Trung Le*
+
+  ![105](./img/bug-report-3.png)
+
+---
+
+## The Oppinions of our PixiJS Game Developers
+
+While the development team is genuinely excited about exploring a new framework, even they do not recommend building or using the framework based on PixiJS.
+
+Although we've successfully developed a full slot game for web desktop, the remaining work required to make the framework production-ready is substantial.
+
+Furthermore, even once the framework is complete, the process of using it to build actual games is significantly more complex compared to the streamlined workflow we already have with Cocos Creator.
+
+## ✅ Final Recommendation
+
+Cocos Creator is **proven**, **feature-complete**, and **deeply integrated** into our current pipeline.  
+
+PixiJS, while powerful as a renderer, lacks critical features and requires substantial additional development. We've also encountered technical roadblocks that reduce productivity and increase maintenance burden.
+
+For these reasons, **we strongly recommend continuing with Cocos Creator** as our main game engine for both current and future slot game development.

docs/faqs/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Engine",
+    "collapsible": true,
+    "collapsed": false,
+    "link": {
+        "title": "Engine"
+    }
+}

docs/faqs/img/pixi-logo.svg

@@ -0,0 +1,54 @@
+<svg width="735" height="289" viewBox="0 0 735 289" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_7_84)">
+<path d="M304.17 288.01V89.99H244.97C244.77 89.99 244.56 89.99 244.34 90C233.7 90.37 225.15 99.12 225.05 109.76C225.05 109.82 225.05 109.88 225.05 109.93V268.4C225.05 268.73 225.07 269.1 225.1 269.51C226 279.71 234.54 287.53 244.77 287.97C245.2 287.99 245.61 288 245.99 288H304.17V288.01Z" fill="#E72264"/>
+<path d="M548.21 287.91C559.24 287.08 567.97 278 568.05 266.93C568.05 266.86 568.05 266.79 568.05 266.72V110.16C568.05 110.1 568.05 110.03 568.05 109.97C568 99.03 559.1 90.11 548.16 90C548.08 90 548 90 547.92 90H488.93V288.02H545.74C546.51 288.02 547.34 287.98 548.21 287.92V287.91Z" fill="#E72264"/>
+<path d="M293.07 90H355.07C361.15 90 369.75 94.92 374.29 101L505.76 277C510.3 283.08 509.05 288 502.98 288H440.98C434.9 288 426.3 283.08 421.76 277L290.28 101C285.74 94.93 286.99 90 293.06 90H293.07Z" fill="#E72264"/>
+<path d="M498.07 90H436.07C429.99 90 421.39 94.92 416.85 101L285.38 277C280.84 283.08 282.09 288 288.16 288H350.16C356.24 288 364.84 283.08 369.38 277L500.85 101C505.39 94.93 504.14 90 498.07 90Z" fill="#E72264"/>
+<path d="M529.07 0C550.05 0 567.07 17.01 567.07 38C567.07 58.99 550.06 76 529.07 76C508.08 76 491.07 58.99 491.07 38C491.07 17.01 508.08 0 529.07 0Z" fill="#E72264"/>
+<path d="M265.07 0C286.05 0 303.07 17.01 303.07 38C303.07 58.99 286.06 76 265.07 76C244.08 76 227.07 58.99 227.07 38C227.07 17.01 244.08 0 265.07 0Z" fill="#E72264"/>
+<path d="M695.07 0H635.07C613.53 0 596.07 17.46 596.07 39V99C596.07 120.54 613.53 138 635.07 138H695.07C716.61 138 734.07 120.54 734.07 99V39C734.07 17.46 716.61 0 695.07 0ZM655.44 39.34V79.84C655.44 85.3 654.35 90.04 652.17 94.05C649.99 98.06 646.88 101.17 642.84 103.38C638.8 105.59 634.01 106.7 628.48 106.7C623.78 106.7 619.72 105.85 616.29 104.16C612.86 102.47 609.98 100.1 607.63 97.06C607.63 97.06 601.08 89.99 607.08 85C613.21 79.9 618.52 86.58 618.52 86.58C619.76 88.31 621.23 89.61 622.93 90.47C624.62 91.34 626.54 91.77 628.69 91.77C630.69 91.77 632.46 91.36 633.98 90.53C635.5 89.7 636.71 88.46 637.61 86.8C638.51 85.14 638.96 83.1 638.96 80.68V39.35C638.96 39.35 638.8 31.01 647.08 31.01C655.36 31.01 655.45 39.35 655.45 39.35L655.44 39.34ZM714.35 98.38C709.82 102.86 703.15 105.56 694.35 106.48C688.3 107.12 683.02 106.7 678.52 105.23C674.02 103.76 669.81 101.21 665.88 97.59C665.88 97.59 659.8 92.35 664.7 85.77C668.38 80.82 675.3 85.96 675.3 85.96C677.92 88.4 680.73 90.2 683.74 91.38C686.75 92.56 690.14 92.95 693.93 92.55C697.3 92.2 699.86 91.28 701.62 89.81C703.38 88.34 704.14 86.5 703.91 84.3C703.71 82.38 702.94 80.86 701.61 79.75C700.28 78.64 698.53 77.75 696.37 77.07C694.21 76.39 691.89 75.79 689.4 75.25C686.91 74.71 684.39 74.02 681.83 73.18C679.27 72.34 676.9 71.23 674.7 69.86C672.5 68.49 670.66 66.64 669.16 64.29C667.66 61.94 666.72 58.95 666.34 55.31C665.86 50.77 666.54 46.77 668.36 43.31C670.19 39.85 672.97 37.07 676.71 34.97C680.45 32.87 684.8 31.56 689.75 31.04C694.91 30.5 699.68 30.9 704.06 32.24C708.44 33.59 712.17 35.63 715.24 38.36C715.24 38.36 719.54 41.97 716.05 48.18C713.34 53.01 705.73 50.11 705.73 50.11C703.29 48.07 700.89 46.62 698.55 45.76C696.2 44.9 693.65 44.61 690.9 44.9C688.08 45.2 685.9 45.97 684.36 47.2C682.82 48.44 682.16 50.06 682.37 52.05C682.56 53.84 683.33 55.23 684.69 56.24C686.05 57.24 687.78 58.05 689.9 58.66C692.01 59.27 694.34 59.86 696.86 60.43C699.39 61 701.93 61.69 704.48 62.5C707.03 63.31 709.4 64.47 711.57 65.98C713.74 67.49 715.6 69.45 717.14 71.86C718.68 74.27 719.65 77.4 720.06 81.25C720.79 88.2 718.89 93.91 714.35 98.38Z" fill="#E72264"/>
+<path d="M107.17 0.340088C47.98 0.340088 0 48.3201 0 107.51C0 108.67 0.02 109.82 0.06 110.97V213.96C0.06 213.96 0.06 213.97 0.06 213.98V224.45C0.06 224.45 0.06 224.45 0.07 224.44V250.33C0.07 250.53 0.06 250.72 0.06 250.92C0.06 251.12 0.07 251.32 0.08 251.52V252H0.09C0.66 271.89 16.95 287.84 36.98 287.84C57.01 287.84 73.47 271.89 74.04 252V213.98H104.66C105.49 214 106.33 214.01 107.16 214.01C166.35 214.01 214.33 166.7 214.33 107.51C214.33 48.3201 166.36 0.340088 107.17 0.340088ZM107.17 140.01C100.62 140.01 84.02 140.01 77.13 140.01H74.07V107.52C74.07 89.3101 88.96 74.5401 107.17 74.5401C125.38 74.5401 140.15 89.3101 140.15 107.52C140.15 125.73 125.38 140.02 107.17 140.02V140.01Z" fill="#E72264"/>
+<path opacity="0.15" d="M36.05 214H73.99V252.01H73.82C73.25 271.9 56.96 287.85 36.93 287.85C16.9 287.85 0.6 271.9 0.03 252.01H0.02V251.53C0.02 251.33 0 251.13 0 250.93C0 250.73 0.01 250.54 0.01 250.34V247.66C1.15 229.87 17.94 214 36.04 214H36.05Z" fill="#1D1D1B"/>
+<g opacity="0.05">
+<path opacity="0.5" d="M0.0599976 168.28V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03V125.45C44.2 128.59 17.77 144.66 0.0599976 168.28Z" fill="black"/>
+<path d="M0.119995 248.37C8.84 241.97 19.42 238.2 30.84 238.2H74.06V213.98H37.03C17.47 213.98 1.48 229.15 0.119995 248.37Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V126.79C43.95 129.74 17.39 146.16 0.0599976 170.27V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C18 213.98 2.34001 228.35 0.26001 246.83C8.97001 240.03 19.73 236.01 31.4 236.01H74.05V213.99H37.02L37.03 213.98Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V128.12C43.68 130.87 16.95 147.69 0.0599976 172.34V213.97C0.0599976 173.71 33.89 140.57 74.05 140.02V140.03Z" fill="black"/>
+<path d="M37.03 213.98C18.53 213.98 3.22002 227.55 0.460022 245.28C9.12002 238.09 20.06 233.8 31.96 233.8H74.05V213.98H37.02H37.03Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V129.46C43.37 132 16.46 149.28 0.0599976 174.53V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C19.06 213.98 4.08998 226.79 0.72998 243.77C9.31998 236.18 20.41 231.6 32.53 231.6H74.06V213.98H37.03Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V130.81C43.01 133.11 15.89 150.93 0.0599976 176.84V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C19.6 213.98 5.00001 226.03 1.07001 242.24C9.54001 234.26 20.77 229.39 33.09 229.39H74.05V213.97H37.02L37.03 213.98Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V132.16C42.6 134.22 15.22 152.65 0.0599976 179.32V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C20.15 213.98 5.92998 225.28 1.47998 240.71C9.79998 232.34 21.14 227.19 33.66 227.19H74.06V213.98H37.03Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V133.52C42.12 135.31 14.43 154.48 0.0599976 182.01V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C20.72 213.98 6.88001 224.54 1.95001 239.19C10.08 230.44 21.53 224.99 34.21 224.99H74.05V213.98H37.02H37.03Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V134.89C41.53 136.39 13.47 156.46 0.0599976 185V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C21.28 213.98 7.83999 223.83 2.48999 237.7C10.4 228.56 21.92 222.79 34.78 222.79H74.06V213.98H37.03Z" fill="black"/>
+</g>
+<g opacity="0.05">
+<path opacity="0.5" d="M74.05 140.03V136.29C40.78 137.48 12.24 158.68 0.0599976 188.47V213.98C0.0599976 173.72 33.89 140.58 74.05 140.03Z" fill="black"/>
+<path d="M37.03 213.98C21.85 213.98 8.80999 223.13 3.10999 236.21C10.74 226.68 22.34 220.59 35.35 220.59H74.06V213.98H37.03Z" fill="black"/>
+</g>
+</g>
+<defs>
+<clipPath id="clip0_7_84">
+<rect width="734.07" height="288.01" fill="white"/>
+</clipPath>
+</defs>
+</svg>