ct-js / docs.ctjs.rocks

Official docs of ct.js game engine

About

What is ct.js?

Ct.js is a 2D game engine and IDE that aims to be powerful and flexible while still being easy to use and learn. It does that by providing extensive documentation, examples, a wide variety of game asset types and their visual editors — all while remaining open to modding, and if modding doesn't help, you can always put plain JS code in your project.

People code in ct.js with TypeScript, JavaScript, or CoffeeScript. Coding is built around the event system, and shared code is implemented as behaviors that can be combined and used by several object templates or levels (as opposed to inheritance).

How ct.js and its games are made?

On a technical level, ct.js games are JavaScript applications that use WebGL for rendering. While not the fastest runtime in the world, this setup is perfectly fine for modern 2D games and allows fast iteration, one-click web export — and two-click desktop builds as well!

Under the hood, ct.js games are based on a custom game framework plus pixi.js as its rendering and sound engine.

Ct.js as a game editor is a web application as well, based on the NW.js framework. The UI is component-based and is run on Riot.js v3, with most of the sensitive parts of the application written as TypeScript ESM modules.

Why?

Ct.js was made to be the cross-platform, always accessible integrated tool that is not stuck in time like most other 2D game engines that use dated renderers, limited feature sets, and have hindering UIs. Ct.js lets you focus on your game's content without worrying about technical details like asset packing and loading, handling different screen resolutions, packing for desktop, and such.

Ct.js is opinionated and gamedev-centric. To make a game, you do not need to know web development or how to summon a demon — all the tools and the knowledge are already in ct.js.

And all this is to be free — as in beer, as in freedom, and as a reproach towards companies too deep in their corporate greed.

Support ct.js on product-hunting sites:

• Like ct.js on AlternativeTo
• Rate ct.js on Slant in different questions

Production builds

See the releases page or jump to itch.io page. Available for Windows, Mac and Linux.

Nightly builds

We host dev builds at itch.io. This page will have nightly versions that are built from the develop branch from our repository. It means that you will get the latest features, improvement, bug fixes, and new bugs daily, out of the oven. Use with caution and have fun. Itch.io app is strongly recommended.

Getting help

For bugs, feature requests, developing questions, please use GitHub issues so we can better track them. For general support about making games, ask a question at our discord server.

Repo structure & tools

• app — an NW.js app, with its configs and static files.
  • data
    • ct.libs — catmods (modules) that ship with ct.js. Feel free to create a pull request with your module!
    • i18n — UI language schemes. Open for pull requests! :)
• src — a source folder that compile into /app folder at a build time.
  • ct.release — the ct.js game library, aka its "core"
  • js — different top-level scripts, including 3rd-party libraries.
  • node_requires — built and copied to the /app directory.
  • pug — HTML sources of editor's windows, written in Pug.
  • riotTags — components that drive UI logic in ct.js. Written in Pug and Riot.js v3.
  • styl — style sheets, written in Stylus.
• branding — logos and icons belong here.
• docs — official docs of ct.js. Edit them here.
• SSCD.js — a fork of a collision library for ct.place.

Developing ct.js

Planning

See the main dev board for hot issues and plans for next releases. Prioritize the "Current release" column, then "To Do", then "Backlog", though if you really want a feature from a backlog to come true right here, right now, no one can stop you :)

Please leave a comment in issues you want to work on so that we can assign you to them and avoid occasional double work from several contributors.

Forking and installing the dev environment

Building ct.js requires Node and npm installed on your machine.

git clone https://github.com/ct-js/ct-js.git ctjs
cd ./ctjs
npm install gulp-cli -g
npm install
gulp -f devSetup.gulpfile.js

Running ct.js from sources

gulp

Use gulp dev instead of just gulp to run a dev service with live-reloading without opening ct.js in its default manner. In either case, you can stop this service in the usual manner for your terminal, e.g. Ctrl+C. If you are encountering unexplained issues, especially when switching to a new branch, run gulp -f devSetup.gulpfile.js again.

VSCode can use this extension to run ct.js with an attached debugger. Before running the debugger, to allow live-reloading, run gulp dev.

Linting

Linting checks for code formatting issues, runs ESLint, and also checks i18n files for extra keys.

gulp lint

There are also separate commands for running specific tests only:

gulp lintJS
gulp lintTags
gulp lintStylus
gulp lintI18n

Getting your changes into production

It's actually easy and robust. We have regular ct.js for core releases and ct.js Nightly as a canary/preview build.

• Once your PR was approved and merged, it gets into the develop branch.
• Every change to develop triggers a CI build, and a new version of ct.js Nightly is released publicly.
  • To automatically update ct.js Nightly, we recommend using the official itch.io app.
• Every now and then maintainers decide to release a public version of ct.js — it involves version bumping, creating and cleaning changelog, updating screenshot, website, presskit data and such. Some stuff is automated, but it still involves manual work and public announcements on different channels. But if your change got into develop, it means it will reach the master branch as well.

Releasing ct.js

This is left for emergencies only, as Gitlab CI should prepare binaries for github and send them to itch.io as well

# Builds docs and adds them to ct.js app
gulp docs
# Recompiles source files, bundles docs, and bakes binaries
gulp packages

# Publishes prebuilt binaries to itch.io
# This assumes that you have an access to ct.js at itch.io :)
gulp deployItchOnly
gulp deployItchOnly --channel next # deploy to a specific itch.io channel

# Creates a draft release on GitHub
# Needs a GITHUB_TOKEN in your environment variables.
# Does nothing on nightly releases
gulp sendGithubDraft

# Combines `gulp packages`, `gulp sendGithubDraft`, and `gulp deployItchOnly`
gulp deploy

The first run will be slow as it will download nw.js binaries. Next runs will use cached files.

Naming conventions and references

Use Gitmoji-flavored Comigoji for naming your commits.

Use Comigo's CSS naming guide for styling

We have some references for ct.js' internals on our wiki.

The ct.js app has a built-in CSS stylebook in the Meta section of the main menu.

docs.ctjs.rocks's Issues

Small error in describing key input in the asteroid shooter tutorial

Here the correct keybinding should be Keyboard.KeyA but it's written Keyboard.A in the doc.

Tutorials and their projects must be updated, as ct.camera and UI layers are introduced.

See ct-js/ct-js@902c92d

• Platformer tutorial
• Shooter tutorial
• Shooter demo
• Puzzle demo
• Platformer demo

Белый экран при запуске на локальной машине

При запуске сайта на локальной машине показывается белая страница и ошибка в консоли браузера "Загрузка модуля по адресу «http://localhost:8080/@id/C:/Users/Diablo/Documents/GitHub/docs.ctjs.rocks-russian/docs/.vuepress/.temp/internal/layoutComponents» была заблокирована из-за неразрешенного MIME-типа («»)."

Translation into hindi

Please assign this issue to me. I am working on it.

Thanks

Modify Step in Platformer Tutorial

I'm busy with other things right now or I'd make a pull request of it instead.

On step "Creating a Robot Character and Ground", it says to 'Now move to the "On Step" tab and add this code:', however it is reusing the default parameter speed in the tutorial causing issues if the person following it appends the code in the tab rather than replacing it due to the default inclusion of this.move();.

Two possible solutions:

1. Change the step to 'Now move to the "On Step" tab and replace the contents with this code:'
2. Change the tutorial so it uses something other than this.speed for the max horizontal speed.

Example code error (Follow a copy of a template called "Character")

Running this code example gives the error:

Adding .template on line 3 fixes it.

Also this.move() is missing at the end but im not sure if it's intentional either.

pages missing in docs!

inside page Introduction to JavaScript, part I: Variables, Properties, Operations some links are not working
currently found ->
properties of Copies
Rooms

Usage of timers, promises, intervals and timeouts for making delayed events in ct.js

In GitLab by @Comigo on Mar 15, 2019, 01:56

null

Building your game and deployment to itch.io

This is a sub-issue related to issue #43

• Create a document section for building your game
• Create a subsection for deployment to itch.io ( can add more subsections at a later stage )

Add gifs that explain how ct.camera.realign(room) works

See https://itch.io/t/795768/what-does-ctcamerarealignroom-actually-do-

[type:bug] Camera is null?

Everything seems to be fine with my game, but I keep getting this console error:

ct.js system code:

it seems that the ct.camera is null.
Thanks!

Ct.types refers to a deprecated page on pixi.js.

(quick note) All the names in ct.js were already updated for pixi.js v5, but docs still refer to v4 names

Vuepress - automatic theme switching

Automatic theme switching does not work on https://docs.ctjs.rocks. When you type this into browser's console, the dark theme becomes active;
document.body.classList.add('dark');

And the colors of current dark theme are very bad(blueish high contrast tones). If you apply the theme below, it changes automatically according to the mode of the system. also the colors are better:
https://github.com/tolking/vuepress-theme-default-prefers-color-scheme

Document background editing process while in-game

E.g. one needs to change a background's texture or its movement speed. Or they need to manually set its coordinates.

Tutorial: "Making a game: top-down crawler"

Turns out many people on Discord struggle to make a top-down non-grid movement, especially with collisions, propulsion and moving objects.

Add ct.u.degToRad, ct.u.radToDeg

Some new methods from v1.5 are not in the docs

• ct.types.isCopy
• ct.u.hexToPixi
• ct.u.pixiToHex

Changes to the ct.js' API to reflect in docs

• ct. is not needed to be written. Properties that dropped the ct. prefix without major changes: meta|camera|templates|rooms|actions|inputs|content|backgrounds|styles|res|emitters|tilemaps|timer|u|pixiApp|stage|loop|fittoscreen|assert|capture|cutscene|desktop|eqs|filters|flow|fs|gamedistribution|inherit|gamepad|keyboard|mouse|pointer|nakama|noise|nanoid|place|random|sprite|storage|touch|transition|ulid|vgui|vkeys|yarn
• ct.sound is now sounds, ct.sound.spawn is now sounds.play
• ct.delta is now u.delta, ct.deltaUi is u.deltaUi
• ct.room is rooms.current
• ct.pixiApp is pixiApp
• fittoscreen is now a hidden built-in API. Controlled through these ⬇
• A wild settings appears:
  • highDensity is a toggleable boolean (retina mode);
  • targetFps configures target FPS and its cap;
  • viewMode is old fittoscreen's mode with one of these values (can be changed during runtime): 'asIs' | 'fastScale' | 'fastScaleInteger' | 'expand' | | 'scaleFit' | 'scaleFill'
• camera is not writable now.
  • What's the alternative?
    • Is it really needed?
• ct.roomWidth and ct.roomHeight are now rooms.current.viewWidth and rooms.current.viewHeight
• /*!%start%*/ injection was removed.
• Base classes appear. Panels and text labels can't have animation events, or animation properties.
• Skeleton support is removed.
• Docs for sounds API.

• Update tutorials to match the new IDE and API

v4: replace this.depth with this.zIndex

The depth property is depreciated and the property now been used is zIndex.

Tips & tricks: working with files (loading and writing)

Though there is a way to save games with localStorage, sometimes it is needed to load/write external files. Though this topic is widely covered by a js community and not a subject to be covered by ct.js functionality (as every API is pretty high-level already and there is no point for adding new catmods or core API for that), it is not obvious for game developers as they expect this to be a part of a game engine.

What needs to be documented:

• the use of include folder in ct.js projects;
• the use of fetch API with examples of loading images & data from include and the web. Possible use cases/examples include:
  • fetching a latest game's version on itch, which is a JSON file (e.g. https://itch.io/api/1/x/wharf/latest?target=comigo/ct&channel_name=win64, see butler docs at itch.io);
  • loading a heavy background image to speed up the loading process (as seen in Shifted).
• working with the file system in desktop apps (ct.fs). Use cases/examples may include:
  • reading a directory's contents (e.g. discovering user-made levels);
  • writing and reading JSON files;
  • deleting files.

Possibly, fs functionality may be abstracted and presented as a ct.js API in ct.desktop.

Russian docs

In GitLab by @Comigo on Mar 2, 2019, 02:29

• Tutorials
• Tips & tricks, Dragonbones
• core's API docs
• image localisation

Feature: generate PDF versions for each locale

Use case: for offline use at schools, subways, for people who prefer working with pdfs (i guess), for print, and as a backup when an internet connection is not stable (it is still the case for 21st century).

This can be achieved relatively easy with one of these modules:

• gulp-markdown-pdf
• electron-pdf as it can use the existing site as a source.
• something along these lines with wkhtmltopdf

Propose edits link

Link at the bottom of documentation pages doesn't work.

Documentation requests (help wanted)

There are numerous topics that would be cool if they were documented in ct.js' docs.

High priority topics

• #68 Web-only builds. Demos. Desktop builds.
• Same for GameJolt (can be merged with the above).

Normal priority

• Gracefully loading and playing music and ambient sounds in web builds (preloading, fading in/out)
• Making and using sub-animations with ct.sprite
• Platformer movement with sloped ground
• Working with nested copies.
• Making a visual novel (based on ct.yarn example)
• Making UI elements that follow gameplay elements
• Shooting to mouse location and turrets
• Dragging copies around with touch/mouse

Low priority

• Making a match-3 game in ct.js
• Making cool effects with emitter tandems. Whirls, implosions/explosions, multi-layered effects, trails.

Pausing a game by stopping Pixi's tickers

In GitLab by @Comigo on Feb 24, 2019, 21:57

The code to pause the game is as following:

PIXI.ticker.shared.speed = 0;
ct.pixiApp.ticker.speed = 0;

And, to unpause:

PIXI.ticker.shared.speed = 1;
ct.pixiApp.ticker.speed = 1;

But it should be documented as a quick tip/tutorial in the docs, because one will never guess on how to do that, even with Pixi.js docs.

From Discord server:

If you are using ct.delta all over your game code, a simple line [...] must effectively disable motion of everything that uses that ct.delta. Default movement system with this.speed and this.direction is included here as well. At this point, the game loop will still work, meaning that UI and stuff will be responsible.
To set ct.delta back to normal, run [...].
So you need to:

1. Spawn a pause menu;
2. Set both tickers to 0;
3. Set them back to 1 when a player presses the "unpause" button