KITH LANGUAGE MANUAL (v1.2)
==========================

KITH is a simple programming language that runs in the browser and prints to the Output box.
Programs are made of commands. Most commands use quoted text like:

print "Hello"

RULES
-----
1) Commands are case-insensitive (PRINT = print).
2) Most commands take ONE quoted string.
3) Lines starting with // are comments.
4) Variables are created with set.
5) Some commands run in blocks and need end.

EXAMPLE PROGRAM
---------------
clear ""
bg "black"
center "KITH Demo"
line "----------------"
set "name,Thomas"
print "name"
replace "Thomas" with "Bowman"
print "name"


CORE COMMANDS
=============

1) PRINTING TEXT
----------------
print "text"
big "text"
small "text"
center "text"
line "text"

Notes:
- If you print a variable name, it prints the variable value.
  Example:
  set "x,hi"
  print "x"     -> prints hi


2) COLORS
---------
color "colorNameOrHex,text"

Examples:
color "red,WARNING"
color "#00ff00,Green text"


3) BACKGROUND
-------------
bg "colorNameOrHex"

Example:
bg "#008080"


4) CLEAR OUTPUT
---------------
clear ""


5) WAIT
-------
wait "seconds"

Example:
wait "1"
wait "0.25"


VARIABLES + INPUT
=================

6) SET VARIABLE
---------------
set "name,value"

Examples:
set "score,0"
set "username,Thomas"


7) INPUT (PROMPT)
-----------------
input "question,variableName"

Example:
input "What is your name?,name"
print "name"

Notes:
- If the user types a number, KITH stores it as a number.
- If Cancel is pressed, input does nothing.


MATH COMMANDS
=============
8) ADD / SUB / MULTI / DIV
--------------------------
add "a,b"
sub "a,b"
multi "a,b"
div "a,b"

Examples:
add "2,3"          -> prints 5
set "a,10"
set "b,2"
div "a,b"          -> prints 5


LINKS + MEDIA
=============
9) LINK
-------
link "label,https://url"
link "label,id,https://url"

Example:
link "Kithala,https://kithala.neocities.org"


10) BUTTON
----------
button "label,https://url"
button "label,id"
button "label,id,https://url"

Examples:
button "Open Google,https://google.com"
button "Start,startBtn"
button "Docs,docsBtn,https://example.com"

Notes:
- If you give an id, you can use it with on click.


11) IMAGE
---------
image "https://url-to-image"


12) SOUND
---------
sound "https://url-to-audio"

Notes:
- Some browsers block autoplay until you interact (click) first.


LOGIC (IF)
==========
13) IF / THEN / ELSE
--------------------
if "condition" then command "data" else command "data"

Conditions supported:
==  !=  >  <  >=  <=

IMPORTANT:
- Conditions must be numeric (numbers or number-variables).

Examples:
set "hp,20"
if "hp>0" then print "Alive" else print "Dead"

set "a,5"
set "b,5"
if "a==b" then color "lime,Equal" else color "red,Not equal"


LOOPS (REPEAT)
==============
14) REPEAT / END
----------------
repeat "count"
  (commands inside)
end

Example:
repeat "3"
  print "Hi"
end

Notes:
- repeat count must be a number.
- There is a max repeat limit to prevent crashes.


INTERACTIVE + GAME COMMANDS
===========================

15) REPLACE
-----------
replace "old" with "new"

This replaces text already shown in Output.

Example:
print "Hello there!"
replace "Hello" with "Hi"

Template:
replace "" with ""

Notes:
- Replacing "" (empty string) is ignored for safety.


16) SCENES + GO TO (NAVIGATION)
------------------------------
scene "name"
  (commands)
end

go to "name"

Example:
scene "menu"
  clear ""
  center "MENU"
  button "Start,startBtn"
end

scene "game"
  clear ""
  center "GAME"
  print "Let’s go!"
end

go to "menu"


17) ON CLICK (EVENT BLOCK)
--------------------------
on click "id"
  (commands)
end

Example:
button "Start,startBtn"

on click "startBtn"
  go to "game"
end


18) WHEN "KEY" IS PRESSED (KEYBOARD EVENT)
------------------------------------------
when "w" is pressed
  (commands)
end

Example:
when "w" is pressed
  print "Pressed W!"
end

Notes:
- Keys are checked in lowercase.


19) DELETE (REMOVE BY ID)
-------------------------
delete "id"

Deletes an element created with an id (like a drawn shape or a button).

Example:
delete "boxOld"


DRAW (SHAPES)
=============
KITH supports TWO draw syntaxes.

20A) DRAW (NEW READABLE FORM)  <-- YOU ASKED FOR THIS
--------------------------------
Syntax:
draw "shape" size "WxH" at x "X" and y "Y"

Example:
draw "square" size "3x3" at x "3" and y "7"

Notes:
- shape: currently only "square"
- WxH: size in grid units like 3x3
- x and y: grid position
- default scale is used automatically
- the shape gets an id you can delete:
  square_X_Y (example: square_3_7)


20B) DRAW (OLD COMPACT FORM)
----------------------------
Syntax:
draw "square,WxH,x,y,scale,id"

Example:
draw "square,3x3,3,2,4,box1"

Then:
delete "box1"


LIMITS + SAFETY
===============
To prevent crashing, KITH has limits like:
- Max repeat count
- Max output lines
- Max string length
- Max go to jumps

If you hit a limit you’ll see:
ERROR: ...


TROUBLESHOOTING
===============
1) My sound won’t autoplay
- Click the page first, then run.

2) My on click doesn’t work
- Make sure the button has an id:
  button "Start,startBtn"
  on click "startBtn" ... end

3) go to says unknown scene
- You must define:
  scene "name" ... end

4) replace didn’t change anything
- replace only changes text already printed.
- make sure the old text exists.

5) draw didn’t show up
- You need to scroll output, and the stage appears when you draw.
- Make sure x and y are numbers inside quotes.

CHANGELOG
=========
v1.0:
- printing, variables, input, math, links/buttons/images/sound, wait/clear/bg, if, repeat

v1.1:
- replace, scene/go to, on click, when key is pressed, delete, draw (old form)

v1.2:
- draw readable form:
  draw "square" size "3x3" at x "3" and y "7"


END OF MANUAL
=============