Giter VIP home page Giter VIP logo

cubing / cubing.js Goto Github PK

View Code? Open in Web Editor NEW
227.0 8.0 41.0 37.31 MB

๐Ÿ›  A library for displaying and working with twisty puzzles. Also currently home to the code for Twizzle.

Home Page: https://js.cubing.net/cubing/

License: GNU General Public License v3.0

JavaScript 0.53% Makefile 0.34% TypeScript 90.81% CSS 1.42% HTML 6.89% Shell 0.01%
library javascript cubing meta puzzle twistypuzzles puzzles rubik rubiks rubiks-cube

cubing.js's Introduction

cubing.js

cubing.js is a collection of JavaScript libraries, still under development.

Twizzle

Twizzle is the spiritual successor to alg.cubing.net, based on cubing.js. It is currently being developed at src/sites/alpha.twizzle.net. See the Twizzle Diaries video series for more information on Twizzle's vision and use cases.

Getting started

If you're just getting started, the easiest way to use cubing.js is through cdn.cubing.net:

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

You can find more documentation at js.cubing.net/cubing/.

Using with node and npm

If you would like to use cubing.js as a library in your package-based projects, make sure you have node and npm installed (installing node will install npm as well). Once you have installed those, you can run:

npm install cubing

Then you can use modules like this:

import { Alg } from "cubing/alg";
import { TwistyPlayer } from "cubing/twisty";

Please note that cubing.js requires ES2022 module compatibility. See here.

Contributing

If you would like to contribute to the development of cubing.js, please refer to our contribution guidelines.

Developing cubing.js itself

Working on cubing.js requires the following tools:

On macOS, you can install these using Homebrew:

brew install git git-lfs node oven-sh/bun/bun

(On other platforms, you'll have to follow individual installation instructions. We recommend using WSL on Windows.)

Once you have these dependencies, you can run the cubing.js source like this (see the contribution guidelines for more details):

git clone https://github.com/cubing/cubing.js && cd cubing.js
make dev
# Now visit http://cubing.localhost:3333

To quickly check any changes for issues, try make test-fast. Run make test for more thorough testing options.

Developing on Windows

We recommend using Microsoft's Windows Subsystem for Linux (WSL) to develop cubing.js on Windows.

Release notes

For release versions and release notes, view the release history on GitHub: https://github.com/cubing/cubing.js/releases

License

This project is licensed under the Mozilla Public License. This means that cubing.js is free to use in any public or private project. We've selected this license so that cubing.js can be used in a large variety of use cases.

However, if you modify the source code of cubing.js to fit your needs then you must publish your modifications to the cubing.js source code (e.g. publish a fork put it on GitHub). See the full license for exact details.

Although you are no longer required to publish code that uses cubing.js, we encourage you to develop your projects as open-source. This way, others can learn from your work and build on it far into the future. It also allows us to tell how features are being used by projects in the community, and what new features are needed.

Fine Print

All original code in this project is dual-licensed as both GPL and MPL, but the codebase contains additional vendored code under the Apache, MIT, and Ubuntu Font licenses. This may affect you if you are forking the source code, as certain parts are not MPL-licensed on their own. But if you are just using cubing.js as a library, you can effectively treat all of cubing.js as if it was MPL-licensed.

Acknowledgments

As of this time, cubing.js primarily contains code by Lucas Garron (@lgarron) and Tom Rokicki (@rokicki). Significant parts of the cubing code also are from:

It also uses the three.js, comlink, and p-lazy libraries. Twizzle also uses the Ubuntu font.

cubing.js's People

Contributors

alex-stockgamblers avatar anicolao avatar benwh1 avatar debater-coder avatar dependabot[bot] avatar dunkonit avatar lgarron avatar nbwzx avatar preethamrn avatar rokicki avatar sachinh19 avatar ticklemepierce avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

cubing.js's Issues

Handle appended moves and move streams

  • Two incoming R moves in short succession should be merged.
  • Simultaneous L R' should animate at the same time. (This matters especially because M' is L R' with a reorientation.)

Square-1, Clock

Other puzzles have notation that is partially compatible. twisty.js will need some abstraction to cover them.

Twizzle wants side-by-side equal-size views (front and back)

I believe the new twizzle app would be nicer if it supported side-by-side equal-sized views, one of the front and one of the back. The current small back view (rear view mirror?) is useful for debugging, but having a back view of the same size would make the interface work much more nicely for actual interactive solves.

Advanced visual features

Puzzles

  • Images for stickers/faces
  • Photorealistic textures & lighting
  • Rounded cubies/stickers
  • Motion blur
  • Show internals
  • Camera settings

Interface

  • Theme colors

Should accept "empty" puzzle

The code should accept the "empty" puzzle with no sets (and an empty solved state and moves that do nothing).

In my UI I'm allowing users to turn on and off various parts of the puzzles (corners/edges/centers) and if they turn everything off, kpuzzle throws. It should not.

Feature parity with other software

Here's a list of other software whose features we should look at:

See more at https://github.com/cubing/cube-code#javascript

Heise Applet Replacement

Ideally, we'd have a nice system that makes it nice to do speedsolves, but provides features like logging of solvs (look at how you do your solves, and how this has changed!), etc.

Variable-duration moves

Half turns should be slow/longer than quarter turns.
It should be possible to specify the time for each base move.

Plugin support

If someone is implementing a new puzzle/feature we didn't anticipate, it would be nice if they could hook into a simple plugin API to control:

  • parsing algs
  • puzzle state
  • puzzle display

Features / Settings

  1. Pick the settings that actually matter.
  2. Try to make as many of these dynamic as possible (i.e. allow changing after the initial constructor).
  • Actually, it might be good to move as many possible settings out of the constructor as possible, and then provide convenience functions for the most common setup pattern.
    • For example, control.speed can always be set with setSpeed after the twistyScene is constructed.
    • It might be cheap enough to construct/remove/hide things like hint stickers "on the fly". Certainly better than creating a new twistyScene.
  • full color/sticker settings (color lists for faces?), image maps
  • custom coloring for e.g. different cube steps (OLL, 6x6x6 centers)
  • transparency (param)
  • bgcolor (transparent default) - is this really necessary?
  • BLD mode
  • Each puzzle: Interface for random scramble?
  • animation/transition curve
  • Config file (thus, standard specs)
  • Callback interface
  • notations?
  • See CubeTwister
  • Playback interface (one level abstracted, but still on same div?)
  • camera settings (location, scale?, orthoQ, etc.)
  • rear view
  • Mouse support
  • Cube panning/rotation
  • static rendering support (for WCA scramblers, etc.)
  • debug mode
  • bandaging?

Drag/touch move input

In principle (and as suggested by three.js demos), it's not hard to capture mouse/touch events and use them to animate moves on the cube. I think the main issue here is handling the in-between animation while someone is moving a layer.

Should include:

  • rendering the (partial) move, with live updating
  • good mobile support
    • needs to interact with touch support from the touch branch.

Simultaneous moves

Title pretty much says it all. Ideally this gets done in as twisty-independent a way as possible.

Java Applet Replacement

Implement a decent set of parameters that make it posible and worthwhile to switch out AnimCube and Randelshofer's appplets for three.js on cube pages. Ideally, this should be able to handle tons of twisties on a page (achievable by flattening the twisties per cubing/twisty.js#12 while not active).

  • AnimCube
  • Randelshofer
  • VisualCube
    • Not a Java applet, but has URL-based configuration

Add stages

3x3x3

  • Fridrich
    • Cross
    • F2L
    • F2L with certain slots unsolved/multislotting?
    • OLL
    • PLL
  • MGLS
    • ELS
    • CLS
  • LL substeps
  • Roux
    • L6E
    • CMLL
  • Petrus
    • 2x2x2
    • 2x2x3
  • ZBLS
  • ZZ

Big Cubes

  • Centers
  • Reduction

Puzzle Wish List

Official

  • Pyraminx (any ordedimensions + edge twisting?)
  • Megaminx (any dimensions)
  • Skewb (any dimensions)
  • Clock (NxNxN?)
  • Square-1 (any number of layers?)

Maybe

  • Pillowed Cubes?
  • Octahedron?
  • Square-2
  • pyra crystal
  • UFO/cheese/anything dihedral
  • KxLxM cuboids

Sliding

  • 15 Puzzle
  • Astrolabacus
  • Black Hole

Shoot for the Moon!

  • Investigate UMC
  • Magic?
  • Sticker-sliding cube
  • Heli cube
  • Anything on gelatinbrain / Jaap's page?

Ideally, I wouldn't need to be the one to implement all of these.

Support setting puzzle state

I'm looking for a way to set the current cube state like so: setCubeState("uuuuuuuuu fffffffff rrrrrrrrr bbbbbbbbb lllllllll ddddddddd"). The specific format/protocol doesn't matter. Is there a way to do this using twisty.js? I found a setPosition method, but this only seems to change the "pointer" pointing to the current move within an algorithm.
Is such a feature even desired? It would probably break some assumptions like v.setPosition(0); v.isIdentity() == true.

Write an alg parser in TypeScript

We have a good parser generator, but we could get some benefits from writing our own:

  • Better error messages for parsing errors
  • Streaming/incremental parsing
  • Very efficient

v2 API Wishlist

Working Draft:

Classes

Classes implemented using prototypes.
All setters should also have a getter.

Twisty

Twisty.animation.setSpeed(ratio);
Twisty.animation.playForwards();
Twisty.animation.playBackwards();
Twisty.animation.pause();
Twisty.animation.playSingleMoveForwards();
Twisty.animation.playSingleMoveBackwards();
Twisty.animation.skipToStart();
Twisty.animation.skipToEnd();
Twisty.animation.setPosition(ms, "animateQuickly" | "immediate")
Twisty.setup.setSolvedState(TwistyState)
Twisty.setAlg(TwistyAlg)

Twisty3x3x3 (prototype: Twisty)

TwistyState

A TwistyState is a ksolve-like extension of the idea of a permutation.

TwistyState.fromAlg()
TwistyState.invert() @returns TwistyState
TwistyState.compose(TwistyState) @returns TWistyState

AnimatingTwistyState

TwistyState.fromAlg()
TwistyState.invert() ?

Alg

An alg is a collection of moves and other algs.
Can be either a straight move sequence, or a group/communtator/conjugate.

Alg.addMoves(?)
Alg.timestampToToken(ms) @returns AlgToken
Alg.tokenToTimestamp(AlgToken) @returns ms
Alg.reparse("<original alg> R U R'")

Alg3x3x3 (prototype: Alg)

AlgToken

DOMAlg ?

// Something for highlighting

TwistyView

new TwistyView(rendererType, div);
  (rendererType == canvas, CSS div, etc.)
  // support shadow DOM where possible?
TwistyView.addPuzzle(puzzle);
TwistyView.setCameraLocation(coords)
TwistyView.fullscreen();
  // Perhaps the client can just use the normal HTML5 API on the div?
// 2-axis View rotation support support

Convenience

Twisty.emulateAnimCubeApplet()
Twisty.emulateRandelshoferApplet()
Twisty.emulateRoofpig

TwistySolver

TwistySolver.solveState(); @returns Alg

TODO

  • Sticker Dragging
  • Keyboard input

Twizzle needs face names on dwell over faces

Twizzle should display the face name (U, F, BL, etc.) on hover over a face. Otherwise it's not at all clear what face is what (especially for puzzles that have no established conventions for face names).

Support mouse-moves in algorithm/animated cube correctly

Right now if you click a move in twizzle, the move gets appended to the algorithm and the move is executed, but there is no coalescing of moves (say, U then U into U2). If you enable automatic coalescing, then clicking the second U causes the cube to "jump" back to the state before the first U and execute a U2; this is jarring and incorrect. This should be improved to behave similarly to the original twizzle (currently at twizzle.cubing.net).

Expose battery power level

I'm not sure if this is needed, but it might be nice, and it's not hard to provide (notwithstanding issue cubing/cuble.js#7).

Pauses (dots) don't work in twizzle

Putting a dot (a short pause) in an algorithm in twizzle does not behave properly. This is because the MoveIndexer returns a BlockMove, and a Pause is not a BlockMove. A lot of signatures need to be changed to permit the move indexer to return a Unit (likely), and then the call sites need to check to see if what was returned was actually a BlockMove or a non-state-change algorithm element such as a pause.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.