docs: a Getting Started Guide for the engine that exists
The old one was written in 2014 and said so. It had the reader clone the
repository, compile it, and then plan a project in an empty folder; it used a
modules/ layout that no longer exists, recommended an IDE that is no longer
sold through a link that no longer resolves, and did not show a sprite until
chapter 10. Its four screenshots had been broken for years by a space between
the brackets.
This replaces it, in two acts.
Act 1 changes a game that already works. Torque2D ships PlanetX, so the reader
plays it, changes one number and feels it, opens the console and breaks
something on purpose, then gives the spaceman a shotgun -- about fifteen lines
of code, every one of which does something visible. Nobody sits in front of an
empty file wondering what goes in it.
Act 2 builds a game of their own, from the New Project dialog to a title
screen, a HUD and a level that restarts without leaking. Every step names the
PlanetX file doing the grown-up version of the same job, so the demo becomes a
worked solution the reader keeps long after they finish.
WRITTEN AGAINST THE ENGINE, NOT AGAINST THE PLAN. Every claim was checked in
engine/source before it went in, and the engine won eight disagreements. The
ones worth knowing: a sprite animates with playAnimation, not setAnimation --
that name belongs to GuiSpriteCtrl and to particle emitters, so it is right in
those guides and would have been wrong here. Deleting an object DOES cancel
the timers posted on it -- SimObject::onRemove calls Sim::cancelPendingEvents
-- so the teardown step teaches the case that actually bites, a timer on
something that is not being deleted reaching into something that is. The New
Particle Asset dialog defaults its target folder to the image's folder, where
particle.taml is not declared, which is the declared-assets trap firing
silently on the happy path.
A reviewer caught the largest error. Naming an object already puts it in a
namespace of that name, so the hero had a name and a redundant class saying
almost the same thing. Steps 8 to 10 now turn on the real distinction: name
the one-of-a-kind thing and get its namespace free, class the twelve coins
because a name is unique and you cannot have twelve of it. PlanetX proves the
cost -- its two spacemen share a class and have no name, which is why its key
handlers write PlanetXGame.level.player2 where the reader's write TheHero.
That correction also turned up a live bug: the coin tested %object.class $=
"Hero", which reads empty once the class is gone, so coins would never have
been collected.
Thirteen screenshots are marked with placeholders and still to be taken.
Two fixes to pages this work proved wrong. Console-Guide showed the echo
prefix with a space it does not have, and did not say that the console throws
a statement's result away -- so a bare expression prints nothing at all, with
no error to explain it. SpriteBase-Guide now notes that the same operation is
playAnimation on a sprite and setAnimation on a GuiSpriteCtrl, because code
moved between them fails with an unknown-command warning that points nowhere
near the cause.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Xh3XULt9PtdCtsaYHGnYE
docs: correct class-guide field/method gaps against the engine source
Verified each gap against the class _ScriptBinding.h / initPersistFields() before
editing:
- Sprite-Guide: document the complex (per-corner) color API (setUseComplexColor,
getUseComplexColor, setComplexColor, getComplexColor, fadeToComplex,
fadeToTimeComplex).
- Scene-Guide: add pickRay and pickRayCollision to the picking example, with their
return formats (object-ID list vs. per-object collision detail).
- SpriteBase-Guide: add the missing NamedFrame field (setNamedImageFrame /
getNamedImageFrame).
- SceneObject-Guide: fix the BlendMode typo (getBlendMode -> setBlendMode).
- TextSprite-Guide: link TextSprite_ScriptBinding.h (was bare text).
- AudioAsset-Guide: AudioAsset has no script methods (no _ScriptBinding.h); clarify
that Volume/Looping/Streaming/VolumeChannel/AudioFile are usable from script as
persistent TAML fields, not as callable get/set methods.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6jsrTtG7fhRRRYG9NvHZW
Replaced GG with TGE
This replaces GarageGames with TorqueGameEngines in all links.
Initial Upload
This commit transfer the wiki from the old repository.