DOCSEARCHbyAlgolia
Submit Docs

cubing.js

repository·main·Indexed 43 days ago

https://github.com/cubing/cubing.js

A collection of JavaScript libraries for working with twisty puzzles, such as Rubik's cubes. It provides tools for algorithm parsing, mathematical modeling of cube movements, and puzzle visualization via web components like <twisty-player>. The package includes CLI tools for calculating algorithm repetition order (order), generating puzzle geometries (puzzle-geometry), and creating random scrambles (scramble). Version 0.63.7-dev requires ES2022 module compatibility.

Tokens
25.8K
Snippets
100
Records
139
Agent score
54%

What's inside cubing.js

  1. License Information for cubing.js

    main

    The cubing.js repository is licensed under the GNU General Public License (GPL) version 3. This is a free, copyleft license that guarantees users the freedom to share and change all versions of the software.

    Key implications of this license:

    • Freedom to use: You have unlimited permission to run the unmodified program.
    • Copyleft: If you modify the software and distribute it, you must pass on the same freedoms to the recipients, including providing access to the source code.
    • No Warranty: The software is provided "as is" without any warranty of any kind.
    • Patent Protection: The license includes provisions to prevent software patents from being used to render the program non-free.

  3. Understand the 'Incompatible With Secondary Licenses' notice

    main

    This source code is marked as "Incompatible With Secondary Licenses" as defined by the Mozilla Public License, v. 2.0. This affects how the code can be combined with software under different licenses.

    This Source Code Form is "Incompatible With Secondary Licenses", as
defined by the Mozilla Public License, v. 2.0.

  4. Quickstart with CDN

    main

    The easiest way to use cubing.js is via cdn.cubing.net. You can import the twisty module and use the <twisty-player> web component directly in your HTML. This is ideal for simple integrations or prototyping.

    <script src="https://cdn.cubing.net/v0/js/cubing/twisty" type="module"></script>
<twisty-player alg="R U R' U R U2' R'"></twisty-player>

  5. How to apply the GNU GPL to your own programs

    main

    If you develop a new program and wish to release it under the GNU GPL to maximize its public utility, follow these steps:

    1. Attach notices to source files

    It is recommended to attach the following notice to the start of each source file. Ensure each file includes a copyright line and a pointer to the full license.

    <one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

    2. Add contact information

    Include information on how to contact you via electronic or paper mail.

    3. Handle terminal interaction

    If your program uses a terminal, it should output a short notice upon starting in interactive mode:

    <program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

    Note: The commands show w and show c should display the appropriate parts of the GPL. For GUI applications, use an "about box" instead.

  7. Include the MPL 2.0 license notice in source files

    main

    When distributing source code from this project, you should include the MPL 2.0 license notice. If you cannot include it in every individual file, you may place the notice in a central location, such as a LICENSE file in a relevant directory, where recipients are likely to find it.

    You are permitted to add additional accurate notices of copyright ownership alongside the license notice.

    This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.

  9. Run the development environment for VR experiments

    main

    To run the cubing.js VR development environment, you need to execute a sequence of commands across three different terminal shells to manage the development server, the bundler, and the local proxy server.

    # 1st shell: Start development mode
make dev

# 2nd shell: Run the parcel bundler
make parcel

# 3rd shell: Start the VR proxy server
cd parcel/vr/server/
make serve

  10. Access the VR experiment interfaces

    main

    Once the development environment is running (after executing the three shells described in the setup guide), you can access the VR experiments via the following URLs:

    • Proxy Interface: http://localhost:333/vr/proxy/proxy.html
    • Main VR Interface: http://localhost:333/vr/index.html (You can append ?showControlPlanes=false to the URL to hide control planes).
    open http://localhost:333/vr/proxy/proxy.html
open http://localhost:333/vr/index.html?showControlPlanes=false

  11. Use experimental cubing streams

    main
    The cubing/stream package provides experimental streaming capabilities for cubing data. Note that this package is based on legacy code and is subject to a complete overhaul in the future. It currently provides event types and WebSocket-based proxy mechanisms for streaming data between clients or servers.

  12. Define puzzles via geometric descriptions

    main

    In addition to using known names, you can define a puzzle using a geometric description string. The description follows a specific syntax:

    1. Base Shape: Starts with one of c (cube), t (tetrahedron), d (dodecahedron), i (icosahedron), or o (octahedron).
    2. Cuts: A series of cuts following the shape. Each cut consists of a type and a distance:
      • f: Cut parallel to faces.
      • v: Cut perpendicular to a ray from the center through a corner.
      • e: Cut perpendicular to a ray from the center through an edge.
      • Distance: A decimal number where 1 is the distance between the center of the puzzle and the center of a face.

    Example: c f 0 v 0.577350269189626 e 0