Merge pull request #83 from bitbybit-dev/develop

docs updated

Author: matas-bitbybit-dev

docs/learn/code/common/base/color/color-usage-examples.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 2
+title: Color Usage Examples
+sidebar_label: Color Usage Examples
+description: Learn how to use colors and apply them to 3D geometry in Bitbybit with examples in Rete, Blockly, and TypeScript.
+tags: [code, color]
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import BitByBitRenderCanvas from '@site/src/components/BitByBitRenderCanvas';
+
+# Applying Colors to 3D Geometry
+
+Colors are essential for visualizing and differentiating objects in your 3D scenes. This tutorial demonstrates how to:
+
+1.  **Create colors:** Using different methods from the `Color` class.
+2.  **Apply these colors:** To the faces and edges of a 3D shape (a cube in this case).
+
+We'll explore this using Rete (visual nodes), Blockly (visual blocks), and TypeScript (code). All examples will draw a cube and allow you to dynamically change its face color while keeping its edge color fixed.
+
+For detailed information on each color function, please refer to the [Color API Documentation](https://docs.bitbybit.dev/classes/Bit.Color.html).
+
+## The Core Idea: Defining and Using Colors
+
+Bitbybit primarily uses **hexadecimal (hex) color strings** (e.g., `#FF0000` for red) when applying colors to drawn objects. The `Color` class provides tools to:
+
+*   **Directly define a hex color:** If you know the hex code.
+*   **Convert RGB to Hex:** If you have Red, Green, and Blue (RGB) values, you can convert them into a hex string. This is useful for creating colors programmatically or dynamically.
+
+In these examples, we'll:
+*   Create a cube using OpenCascade Technology (OCCT) via `bitbybit.occt.shapes.solid.createCube`.
+*   Use `bitbybit.color.rgbToHex` to dynamically create a hex color for the cube's faces.
+*   Use `bitbybit.color.hexColor` to define a fixed hex color for the cube's edges.
+*   Apply these colors when drawing the cube using `bitbybit.draw.drawAnyAsync` with appropriate drawing options.
+
+## Live Examples
+
+Click through the tabs below to see the implementation. You can interact with the "Number Slider" in the Rete example or change the `colorParam` in Blockly/TypeScript to see the cube's face color update.
+
+<Tabs groupId="vectors-live-examples">
+<TabItem value="rete" label="Rete">
+    <BitByBitRenderCanvas
+    requireManualStart={true}
+    script={{"script":"{\"id\":\"rete-v2-json\",\"nodes\":{\"1edcd326bca71db9\":{\"id\":\"1edcd326bca71db9\",\"name\":\"bitbybit.math.numberSlider\",\"customName\":\"number slider\",\"data\":{\"options\":{\"min\":0,\"max\":255,\"step\":0.1,\"width\":350,\"updateOnDrag\":false},\"number\":71.1},\"inputs\":{},\"position\":[180.19574181641272,1338.7582581486993]},\"769e2845f3e8f14e\":{\"id\":\"769e2845f3e8f14e\",\"name\":\"bitbybit.color.rgbToHex\",\"customName\":\"rgb to hex\",\"async\":false,\"drawable\":false,\"data\":{\"genericNodeData\":{\"hide\":false,\"oneOnOne\":false,\"flatten\":0,\"forceExecution\":false},\"r\":255,\"g\":0,\"b\":255,\"min\":0,\"max\":255},\"inputs\":{\"r\":{\"connections\":[{\"node\":\"1edcd326bca71db9\",\"output\":\"result\",\"data\":{}}]},\"b\":{\"connections\":[{\"node\":\"1edcd326bca71db9\",\"output\":\"result\",\"data\":{}}]}},\"position\":[699.3462246539564,1252.9838222454043]},\"bcdc3b70d3a8359a\":{\"id\":\"bcdc3b70d3a8359a\",\"name\":\"bitbybit.occt.shapes.solid.createCube\",\"customName\":\"cube\",\"async\":true,\"drawable\":true,\"data\":{\"genericNodeData\":{\"hide\":true,\"oneOnOne\":false,\"flatten\":0,\"forceExecution\":false},\"size\":6,\"center\":[0,0,0],\"originOnCenter\":true},\"inputs\":{},\"position\":[1125.2182618459733,824.1816189607747]},\"6ca6ab70637cce68\":{\"id\":\"6ca6ab70637cce68\",\"name\":\"bitbybit.draw.drawAnyAsync\",\"customName\":\"draw any async\",\"async\":true,\"drawable\":true,\"data\":{\"genericNodeData\":{\"hide\":false,\"oneOnOne\":false,\"flatten\":0,\"forceExecution\":false}},\"inputs\":{\"options\":{\"connections\":[{\"node\":\"ea659597d36f4c4a\",\"output\":\"result\",\"data\":{}}]},\"entity\":{\"connections\":[{\"node\":\"bcdc3b70d3a8359a\",\"output\":\"result\",\"data\":{}}]}},\"position\":[1608.9491866799408,972.1859613807756]},\"ea659597d36f4c4a\":{\"id\":\"ea659597d36f4c4a\",\"name\":\"bitbybit.draw.optionsOcctShapeSimple\",\"customName\":\"options occt shape simple\",\"async\":false,\"drawable\":false,\"data\":{\"genericNodeData\":{\"hide\":false,\"oneOnOne\":false,\"flatten\":0,\"forceExecution\":false},\"precision\":0.01,\"drawFaces\":true,\"faceColour\":\"#ff0000\",\"drawEdges\":true,\"edgeColour\":\"#ffffff\",\"edgeWidth\":10},\"inputs\":{\"faceColour\":{\"connections\":[{\"node\":\"769e2845f3e8f14e\",\"output\":\"result\",\"data\":{}}]},\"edgeColour\":{\"connections\":[{\"node\":\"005c5f3ae7cc62fd\",\"output\":\"result\",\"data\":{}}]}},\"position\":[1118.9540120112902,1174.0527117682532]},\"005c5f3ae7cc62fd\":{\"id\":\"005c5f3ae7cc62fd\",\"name\":\"bitbybit.color.hexColor\",\"customName\":\"hex color\",\"async\":false,\"drawable\":false,\"data\":{\"genericNodeData\":{\"hide\":false,\"oneOnOne\":false,\"flatten\":0,\"forceExecution\":false},\"color\":\"#ffffff\"},\"inputs\":{},\"position\":[698.0846241884296,1673.970997209529]}}}","version":"0.20.4","type":"rete"}}
+    title="Color Usage Example"
+    />
+</TabItem>
+<TabItem value="blockly" label="Blockly">
+  <BitByBitRenderCanvas
+    requireManualStart={true}
+    script={{"script":"<xml xmlns=\"https://developers.google.com/blockly/xml\"><variables><variable id=\"ou3V^EMJ9J08Qg;#)~1q\">colorParam</variable><variable id=\"M62PH(qQgTe~]sDDIuOP\">faceColor</variable><variable id=\"LRFU/eK]P~/NYo4*=j6?\">edgeColor</variable></variables><block type=\"variables_set\" id=\"38iZ[`_XIZhPf6Y(Pl;3\" x=\"-44\" y=\"-713\"><field name=\"VAR\" id=\"ou3V^EMJ9J08Qg;#)~1q\">colorParam</field><value name=\"VALUE\"><block type=\"math_number\" id=\"k9S%^!NS%^I:9S^@0WVm\"><field name=\"NUM\">0</field></block></value><next><block type=\"variables_set\" id=\"Rvimt/4oW~9_hD$SbQ[p\"><field name=\"VAR\" id=\"M62PH(qQgTe~]sDDIuOP\">faceColor</field><value name=\"VALUE\"><block type=\"bitbybit.color.rgbToHex\" id=\"rOVeF[Ic=b-sD#]1-~;:\"><value name=\"R\"><block type=\"variables_get\" id=\",@s$V~g[}qu1,w?VJojv\"><field name=\"VAR\" id=\"ou3V^EMJ9J08Qg;#)~1q\">colorParam</field></block></value><value name=\"G\"><block type=\"math_number\" id=\"wH1|Q1ht/tWhngAsrGFN\"><field name=\"NUM\">255</field></block></value><value name=\"B\"><block type=\"variables_get\" id=\",;9LOnS|V7*gyTNw:Y60\"><field name=\"VAR\" id=\"ou3V^EMJ9J08Qg;#)~1q\">colorParam</field></block></value><value name=\"Min\"><block type=\"math_number\" id=\":j{p0?[jb4:{T9Y)}s|3\"><field name=\"NUM\">0</field></block></value><value name=\"Max\"><block type=\"math_number\" id=\"amrfpG8;8m(|Y.dThgaP\"><field name=\"NUM\">255</field></block></value></block></value><next><block type=\"variables_set\" id=\"m{InLt}Pa?%2:0a?}:BV\"><field name=\"VAR\" id=\"LRFU/eK]P~/NYo4*=j6?\">edgeColor</field><value name=\"VALUE\"><block type=\"bitbybit.color.hexColor\" id=\"wkSZyf8CvM3?!{%ekD.*\"><value name=\"Color\"><block type=\"colour_picker\" id=\"W~#?iL)/so7+9d||BMx]\"><field name=\"COLOUR\">#0000ff</field></block></value></block></value><next><block type=\"bitbybit.draw.drawAnyAsyncNoReturn\" id=\"OW6M.~AOM{Wc8{@:QSnI\"><value name=\"Entity\"><block type=\"bitbybit.occt.shapes.solid.createCube\" id=\"W_g)j=?pu1UZX6m9ikvy\"><value name=\"Size\"><block type=\"math_number\" id=\"PK@4;(K|%eZk3FlO%,Og\"><field name=\"NUM\">6</field></block></value><value name=\"Center\"><block type=\"bitbybit.point.pointXYZ\" id=\"EDLTe3VDq,d]I=9Sd=pA\"><value name=\"X\"><block type=\"math_number\" id=\"j;`E]11QQ=LMwiIEQP%2\"><field name=\"NUM\">0</field></block></value><value name=\"Y\"><block type=\"math_number\" id=\"8THcRcMfqjLEvoE-|mS4\"><field name=\"NUM\">0</field></block></value><value name=\"Z\"><block type=\"math_number\" id=\"-HdCtxnF=!gWm(n7~F`h\"><field name=\"NUM\">0</field></block></value></block></value><value name=\"OriginOnCenter\"><block type=\"logic_boolean\" id=\"EikmG(m^B@.wHf]mbr.t\"><field name=\"BOOL\">TRUE</field></block></value></block></value><value name=\"Options\"><block type=\"bitbybit.draw.optionsOcctShapeSimple\" id=\"Xer|SXX?3(;:_$]nJd~4\"><value name=\"Precision\"><block type=\"math_number\" id=\"XDC1n5`jM4M`~oidXawI\"><field name=\"NUM\">0.01</field></block></value><value name=\"DrawFaces\"><block type=\"logic_boolean\" id=\"JFm=4(8;;l!P=}3!17NU\"><field name=\"BOOL\">TRUE</field></block></value><value name=\"FaceColour\"><block type=\"variables_get\" id=\"qM@e$@,a],p7vg}V0)X,\"><field name=\"VAR\" id=\"M62PH(qQgTe~]sDDIuOP\">faceColor</field></block></value><value name=\"DrawEdges\"><block type=\"logic_boolean\" id=\"k;_gkrL6|CW_#6B=|VRY\"><field name=\"BOOL\">TRUE</field></block></value><value name=\"EdgeColour\"><block type=\"variables_get\" id=\"|vFZK~zc@kNEBZ((HEPt\"><field name=\"VAR\" id=\"LRFU/eK]P~/NYo4*=j6?\">edgeColor</field></block></value><value name=\"EdgeWidth\"><block type=\"math_number\" id=\"j4zOo{{[w0;x]Fsw6+7;\"><field name=\"NUM\">10</field></block></value></block></value></block></next></block></next></block></next></block></xml>","version":"0.20.4","type":"blockly"}}
+    title="Color Usage Example"
+    />
+</TabItem>
+<TabItem value="typescript" label="TypeScript">
+<BitByBitRenderCanvas
+    requireManualStart={true}
+    script={{"script":"const start = async () => {\n\n    const colorParam = 55;\n    const rgbToHexOptions = new Bit.Inputs.Color.RGBMinMaxDto();\n    rgbToHexOptions.r = colorParam;\n    rgbToHexOptions.b = colorParam;\n    const faceColor = bitbybit.color.rgbToHex(rgbToHexOptions);\n\n    // This might look strange as you could just assign the string to edgeColor directly, \n    // but this identity function is nice to have in visual prgramming editors - check Rete & Blockly\n    // examples\n    \n    const edgeColor = bitbybit.color.hexColor({ color: \"#ff0000\" });\n\n    const cubeOptions = new Bit.Inputs.OCCT.CubeDto();\n    cubeOptions.size = 6;\n    const cube = await bitbybit.occt.shapes.solid.createCube(cubeOptions);\n\n    const drawOpt = new Bit.Inputs.Draw.DrawOcctShapeSimpleOptions();\n    drawOpt.faceColour = faceColor;\n    drawOpt.edgeColour = edgeColor;\n    drawOpt.edgeWidth = 10;\n    bitbybit.draw.drawAnyAsync({ entity: cube, options: drawOpt });\n}\n\nstart();","version":"0.20.4","type":"typescript"}}
+    title="Color Usage Example"
+    />
+</TabItem>
+</Tabs>
+
+## Conclusion
+
+These examples illustrate basic yet powerful ways to manage and apply colors in Bitbybit.
+*   For static colors, defining them directly as hex strings (optionally via `color.hexColor`) is straightforward.
+*   For dynamic or programmatically generated colors, converting from RGB values (using `color.rgbToHex`) provides great flexibility.
+
+Experiment with different RGB values and hex codes to explore the color possibilities for your 3D creations!

docs/learn/getting-started/rete/typescript-editor-component.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 4
+title: Why There's TypeScript Editor Inside Rete?
+sidebar_label: TypeScript in Rete Editor
+description: Understanding the synergy between visual programming and text-based scripting (TypeScript, JavaScript, JSON) within Bitbybit's Rete editor.
+tags: [getting-started, rete, typescript]
+---
+
+<img 
+  class="category-icon-small" 
+  src="https://s.bitbybit.dev/assets/icons/white/code-icon.svg" 
+  alt="Coding editors category icon" 
+  title="Coding editors category icon" /> 
+
+import Admonition from '@theme/Admonition';
+
+You might have noticed that Bitbybit's Rete visual programming editor includes integrated editors for TypeScript, JavaScript, and even JSON. At first glance, this might seem counterintuitive. If visual programming is so powerful, why "cheat" by including code editors?
+
+The answer lies in our philosophy of providing both an intuitive entry point and a pathway to deeper control and understanding. Visual programming is fantastic for many things, but it's one tool in a larger creative and development toolkit.
+
+## Visual Programming: The Intuitive Surface
+
+Wiring algorithms together visually with nodes and connections in Rete is:
+
+*   **Intuitive:** It often maps more directly to how we think about data flow and processes.
+*   **Expressive:** Complex relationships can be visualized and understood quickly.
+*   **Engaging:** It's a fun and interactive way to build logic, especially for those new to programming or exploring new domains like 3D geometry.
+
+Bitbybit offers a vast library of pre-built Rete components (currently over 1,300 and growing!). These components encapsulate a significant amount of underlying code, making complex operations accessible through simple visual blocks.
+
+<Admonition type="info" title="The Iceberg Analogy">
+    Think of the visual components as the visible tips of icebergs. They are powerful and useful on their own. However, beneath each one lies a much larger, more intricate body of code—the "deep ocean" of algorithms and logic that makes them work.
+</Admonition>
+
+## Scripting Editors: Your Submarine for Deeper Exploration
+
+While visual components cover a vast range of functionalities, there are times when you need to dive deeper. This is where the integrated scripting editors become invaluable. They are your "submarines," allowing you to:
+
+1.  **Access Unexposed Functionality:**
+    *   Not every single feature or parameter of underlying libraries (like BabylonJS can be exposed as a visual node. Sometimes, for fine-grained control or to access very specific, less commonly used features, writing a few lines of code is the most direct and efficient way.
+    *   **Example:** You might want to tweak an advanced particle system property in BabylonJS that doesn't have a dedicated Rete node yet.
+
+2.  **Implement Custom Logic:**
+    *   There will always be scenarios unique to your project that require custom logic not covered by existing components. Instead of waiting for a new component, you can implement it directly with TypeScript or JavaScript.
+    *   **Example:** "Ugh, if only I could just write these five lines of code to combine these data points in a very specific way..." With the script editor, you can!
+
+3.  **Prototype and Extend:**
+    *   If you find yourself repeatedly writing the same custom script, it might be a candidate for a new, reusable Rete component. The script editor is a great place to prototype this logic. If the idea proves to be generic and useful, we might even incorporate it as a new official component in a future release.
+
+4.  **Debug and Understand:**
+    *   Sometimes, seeing the underlying data or a snippet of code can help you understand why a visual graph isn't behaving as expected. The JSON editor can be useful for inspecting the raw structure of your Rete graph.
+
+5.  **Overcome Limitations and Avoid Getting Stuck:**
+    *   One of the most powerful aspects of this hybrid approach is that you're rarely truly "stuck." If a visual approach hits a wall, you have an alternative. This flexibility is crucial for more complex projects and continuous development.
+
+## A Pathway for Growth: From Explorer to Developer
+
+Bitbybit is designed to be a learning platform. We want to help users grow from curious explorers of visual programming to confident developers capable of tackling complex challenges.
+
+*   **Visual Programming as a Gateway:** Rete provides an accessible and engaging entry point. It lowers the barrier to creating sophisticated 3D scenes and algorithmic designs.
+*   **Scripting as the Next Step:** As your projects become more ambitious, or your curiosity drives you to understand the "how," the scripting editors are there to support your journey. Learning to read and write code unlocks a new level of capability and understanding.
+
+While "vibe coding" and AI-assisted development are exciting trends, the fundamental ability to understand and write code remains an invaluable skill. Think of visual programming as your map and compass, and scripting as your diving gear—both essential for exploring the vast ocean of possibilities.
+
+<Admonition type="tip" title="Practical Example">
+    Want to see this hybrid approach in action?
+    <ul>
+        <li>Check out tutorials (like those found at [Bitbybit School](https://bitbybit.dev/school/courses/typescript-component-for-magical-powers-in-rete)) that might show how scripting can complement visual graphs.</li>
+        <li>Explore live demo projects (like the one at [Magical Paricles Project](https://bitbybit.dev/projects/public/HyCMepiRhTWfua1QRaba/project-magical-particles-by-author-bitbybit)) where this synergy is applied.</li>
+    </ul>
+</Admonition>
+
+## It's Not "Either/Or" — It's "Both/And"
+
+The inclusion of TypeScript, JavaScript, and JSON editors within the Rete environment isn't about choosing one paradigm over the other. It's about providing a flexible, powerful, and adaptable platform where you can use the best tool for the task at hand, and grow your skills along the way.
+
+Happy exploring, and happy coding!