Programming Language PG0.5
Library Reference
--
# Introduction
PG0 is a programming language designed for learning programming.
PG0.5 extends the PG0 programming language.

This is a reference for the following libraries. 
* Screen API (screen.pg0)
* Mathematical API (math.pg0)
* String API (string.pg0)
* Input/Output API (io.pg0)
* Network API (net.pg0)

# Restrictions
This library has the following restrictions. 
* The operating environment is PG0 (web version) and PG0 (Windows version). 
* Operating speed and drawing speed may vary depending on the device and web browser. 
* Sound playback may not function on iOS due to security restrictions. 
* The specifications of each API may change in the future. 

# Screen API (screen.pg0)
Can be used with the following import statement. 
	#import("lib/screen.pg0")

startScreen(width, height, option)
	* Description
		Starts the screen.
		Displays a screen of the specified size on the web browser.
	* Parameters
		width - Screen width (number)
		height - Screen height (number)
		option - Specify options as an associative array.
					{"color": Hexadecimal color code (string), "fit": Flag whether to adapt to screen size(number)}
	* Return Value
		0

sleep(time)
	* Description
		Stops processing for a certain period of time.
	* Parameters
		time - Specify the stopping time in milliseconds as a numerical value.
	* Return Value
		0

time()
	* Description
		Gets the current time (UTC).
	* Parameters
		None
	* Return Value
		Returns the number of milliseconds that have passed since January 1, 1970 00:00:00.

timeString(time, format)
	* Description
		Format a time into a date/time string.
	* Parameters
		time - Number of milliseconds elapsed since January 1, 1970 00:00:00
		format - date and time format. If omitted, the string will be formatted according to the locale.
					YYYY - year
					MM or M - month
					DD or D - day
					hh or h - hour
					mm or m - minutes
					ss or s - seconds
	* Return Value
		date and time string

startOffscreen()
	* Description
		Start off-screen and draw the screen display off-screen.
	* Parameters
		None
	* Return Value
		0

endOffscreen()
	* Description
		Exit off-screen and draw the contents of the off-screen to the screen.
	* Parameters
		None
	* Return Value
		0

startMask(option)
	* Description
		Start mask drawing mode.
		While in mask drawing mode, only the areas you draw on will remain visible; everything else will be transparent.
	* Parameters
		option - Specify options as an associative array.
					{"destination": Mask destination (string)}
					If you specify "out", the drawn area will become transparent.
	* Return Value
		0

endMask()
	* Description
		Exit mask drawing mode.
	* Parameters
		None
	* Return Value
		0

clearRect(x, y, width, height)
	* Description
		Makes the area transparent.
	* Parameters
		x - upper left horizontal coordinate (number)
		y - vertical coordinate of top left (number)
		width - width (number)
		height - height (number)
	* Return Value
		0

drawLine(x1, y1, x2, y2, option)
	* Description
		Draw a line.
	* Parameters
		x1 - starting horizontal coordinate (number)
		y1 - starting vertical coordinate (number)
		x2 - horizontal coordinate of end (number)
		y2 - vertical coordinate of end (number)
		option - Specify options as an associative array.
					{"width": line width (number), "color": hexadecimal color code (string)}
	* Return Value
		0

drawRect(x, y, width, height, option)
	* Description
		Draw a rectangle.
	* Parameters
		x - upper left horizontal coordinate (number)
		y - vertical coordinate of top left (number)
		width - width (number)
		height - height (number)
		option - Specify options as an associative array.
					{"width": line width (number), "color": hexadecimal color code (string), "fill": fill (number)}
					Setting the fill to 1 will fill the rectangle with the specified color.
	* Return Value
		0

drawCircle(x, y, radiusX, option)
	* Description
		Draw a circle.
	* Parameters
		x - horizontal coordinate of the center of the circle (number)
		y - vertical coordinate of the center of the circle (number)
		radiusX - horizontal radius (number)
		option - Specify options as an associative array.
					{"width": line width (number), "color": hexadecimal color code (string), "fill": fill (number), "radius_y": vertical radius (number), "rotation": tilt of the circle (radians), "start": angle clockwise from the X-axis where the circle starts (radians), "end": angle clockwise from the X-axis where the circle ends (radians), "close": connect both ends of the arc (number)}
					Setting fill to 1 will fill the circle with the specified color.
					When radius_y is omitted, the radius is the same as radiusX.
					Setting close to 1 connects both ends of the arc with a straight line.
	* Return Value
		0

drawPolyline(coordinates, option)
	* Description
		Draw a series of straight lines connected by several coordinates.
	* Parameters
		coordinates - Array of coordinates
						Ex) drawPolyline({{100, 100}, {200, 100}, {150, 50}}, {"close": 1}) // Triangle
		option - Specify options as an associative array.
					{"width": line width (number), "color": hexadecimal color code (string), "fill": fill (number), "close": connect the last line with the first line (number)}
	* Return Value
		0

drawFill(x, y, color)
	* Description
		Fills the specified coordinates with the specified color.
		Traces adjacent pixels and fills them with specified color.
	* Parameters
		x - horizontal coordinate (number) to start filling
		y - vertical coordinate to start filling (number)
		color - hexadecimal color code (string)
	* Return Value
		0

drawScroll(x, y)
	* Description
		Scroll the screen.
		Areas that extend beyond the screen will be displayed on the opposite side.
	* Parameters
		x - horizontal scroll amount (number)
		y - vertical scroll amount (number)
	* Return Value
		0

createImage(x, y, width, height, option)
	* Description
		Creates an image of the specified area.
		The returned Image ID can be drawn with drawImage().
	* Parameters
		x - upper left horizontal coordinate (number)
		y - vertical coordinate of top left (number)
		width - width (number)
		height - height (number)
		option - Specify options as an associative array.
					{"id": Image ID (number)}
					If an id is specified, it replaces the existing image.
	* Return Value
		Image ID

drawImage(id, x, y, option)
	* Description
		Draws an image of the specified Image ID.
	* Parameters
		id - Image ID
		x - upper left horizontal coordinate (number)
		y - vertical coordinate of top left (number)
		option - Specify options as an associative array.
					{"width": width (number), "height": height (number), "angle": drawing angle (radians), "alpha": transparency (number)}
					When only one of width and height is specified, the other is the size of the original image.
					alpha is specified between 0.0 and 1.0.
	* Return Value
		0

drawText(text, x, y, option)
	* Description
		Draw text.
	* Parameters
		text - the text to draw (string)
		x - starting horizontal coordinate (number)
		y - starting vertical coordinate (number)
		option - Specify options as an associative array.
					{"width": line width (number), "color": hexadecimal color code (string), "fill": fill (number), "fontstyle": font style (string), "fontsize": font size (number), "fontface": font (string)}
					The default for fill is 1, and if you specify 0, hollow characters will be drawn.
					Specify the font style as normal, bold, italic, or oblique.
	* Return Value
		0

measureText(text, option)
	* Description
		Gets the text drawing size.
	* Parameters
		text - text (string)
		option - Specify options as an associative array.
					{"fontstyle": font style (string), "fontsize": font size (number), "fontface": font (string)}
					Specify the font style as normal, bold, italic, or oblique.
	* Return Value
		drawing size
		{"width": width, "height": height}

rgbToPoint(x, y)
	* Description
		Gets the color at the specified coordinates.
	* Parameters
		x - horizontal coordinate (number)
		y - vertical coordinate (number)
	* Return Value
		RGB array
		{"r": numbers up to 255 to indicate red, "g": numbers up to 255 to indicate green, "b": numbers up to 255 to indicate blue}

rgbToHex(rgb)
	* Description
		Converts an RGB array to hexadecimal color code.
	* Parameters
		rgb - RGB array
				{"r": numbers up to 255 to indicate red, "g": numbers up to 255 to indicate green, "b": numbers up to 255 to indicate blue}
				The keys are case-insensitive.
	* Return Value
		Hexadecimal color code (string)

hexToRgb(hex)
	* Description
		Converts a hexadecimal color code to an RGB array.
	* Parameters
		hex - Hexadecimal color code (string)
	* Return Value
		RGB array
		{"r": numbers up to 255 to indicate red, "g": numbers up to 255 to indicate green, "b": numbers up to 255 to indicate blue}

inTouch()
	* Description
		Returns the touch position.
	* Parameters
		None
	* Return Value
		touch state
		{"x": horizontal coordinate, "y": vertical coordinate, "touch": touch state, "button": button, "pos": {{horizontal coordinate, vertical coordinate}, ...}}
		If the touch status is 0, it is not currently touched and will be the last touched coordinate.
		For button, 0 is left click, 1 is middle (wheel) click, and 2 is right click.
		pos contains multi-touch coordinates.

inKey(key)
	* Description
		Returns keyboard input.
	* Parameters
		key - Specifies the key string to check if pressed.
				If specified as an array, check that all key strings in the array are pressed.
				The key string will be equivalent to JavaScript'sKeyboardEvent.key.
	* Return Value
		If no argument is specified, an array of pressed key strings is returned.
		If the argument is specified as a string, it returns 1 if the key is pressed and 0 if not.
		If the argument is specified as an array, it returns 1 if all keys are pressed and 0 if any keys are not pressed.

playSound(note, start, end, volume = 1)
	* Description
		Plays the specified frequency for the specified time.
	* Parameters
		note - frequency (number)
				If a string is specified, it will be converted to the corresponding frequency. If you put a number after it, it will be converted to an octave.
				'C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'
				When the octave is omitted it is 4. Flats (b) are not supported.
					Ex) playSound("C4", 0, 500)
		start - milliseconds until the sound starts (number)
		end - length of the sound from start in milliseconds (number)
		volume - volume, default is 1 (number)
	* Return Value
		0

playMusic(notes, option)
	* Description
		Play multiple frequencies in sequence.
	* Parameters
		notes - Array of notes
				{note, length, volume}
				If a string is specified, it will be converted to the corresponding frequency. If you put a number after it, it will be converted to an octave.
				'C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'
				When the octave is omitted it is 4. Flats (b) are not supported.
					Ex) playMusic({{"C4", 500}, {"D4", 500}, {"E4", 500}})
				volume is optional.

				The following keys and values in the array have a special meaning.
				start: start position, if several sounds are played at the same time, set the start position to 0 and another sound.
					Ex) playMusic({{"C4", 800}, {"start": 0}, {"E4", 800}, {"start": 0}, {"G4", 800}})
				volume: Volumes after this.
		option - Specify options as an associative array.
					{"repeat": repetition flag(number)}
	* Return Value
		0

bgm(notes, option)
	* Description
		Plays background music.
		Stops the background music that is playing, if any, then plays notes repeatedly.
		Sound effects started with playSound() or playMusic() keep playing.
		Without notes, stops the background music.
			Ex) bgm({{"C4", 500}, {"E4", 500}, {"G4", 500}})
			Ex) bgm() // stop the background music
	* Parameters
		notes - Array of notes in the same format as playMusic(), optional
		option - Specify options in an associative array.
					{"repeat": repeat flag (number)}
					Default is 1 (repeat). 0 plays the notes once.
	* Return Value
		0

stopSound()
	* Description
		Stop any sound that is playing.
		Background music started with bgm() is stopped as well.
	* Parameters
		None
	* Return Value
		0

# Mathematical API (math.pg0)
Can be used with the following import statement. 
	#import("lib/math.pg0")

abs(num)
	* Description
		Returns the absolute value.
	* Parameters
		num - number
	* Return Value
		Absolute value

atan(num)
	* Description
		Returns the arctangent in radians.
	* Parameters
		num - number
	* Return Value
		arctangent of argument

atan2(y, x)
	* Description
		Returns the angle from the origin to the point (x, y) in radians.
		The angle is measured from the positive x axis and lies between -π and π.
			Ex) atan2(1, 1) // 0.785... (45 degrees)
	* Parameters
		y - Vertical value
		x - Horizontal value
	* Return Value
		Angle in radians

cos(num)
	* Description
		Returns the cosine.
	* Parameters
		num - number
	* Return Value
		cosine of argument

exp(num)
	* Description
		Returns e (the base of the natural logarithm) raised to the power of num.
	* Parameters
		num - number
	* Return Value
		e raised to the power of num

log(num)
	* Description
		Returns the natural logarithm.
	* Parameters
		num - number
	* Return Value
		natural logarithm

random(seed)
	* Description
		Returns a random number.
		When seed is given, switches to a reproducible sequence that starts from that seed and returns its first value.
		Following random() calls continue the same sequence.
		Without a seed ever given, a different random number is returned each time.
	* Parameters
		seed - Seed of the sequence (number or string), optional
	* Return Value
		Random number greater than or equal to 0 and less than 1

sign(num)
	* Description
		Returns a flag indicating whether the sign of a number is positive or negative.
	* Parameters
		num - number
	* Return Value
		1 - positive
		-1 - negative
		0 - zero

sin(num)
	* Description
		Returns the sine.
	* Parameters
		num - number
	* Return Value
		sine of argument

sqrt(num)
	* Description
		Returns the square root.
	* Parameters
		num - number
	* Return Value
		square root

tan(num)
	* Description
		Returns the tangent.
	* Parameters
		num - number
	* Return Value
		tangent of argument

pow(base, exponent)
	* Description
		Returns the base raised to the power of the exponent.
	* Parameters
		base - Base
		exponent - Exponent
	* Return Value
		The base raised to the power of the exponent

max(a, b, ...)
	* Description
		Returns the largest of the arguments.
		When an array is given, its elements are compared.
			Ex) max(1, 5, 3) // 5
			Ex) max({4, 2, 9}) // 9
	* Parameters
		a, b, ... - Numbers or arrays of numbers
	* Return Value
		Largest value

min(a, b, ...)
	* Description
		Returns the smallest of the arguments.
		When an array is given, its elements are compared.
	* Parameters
		a, b, ... - Numbers or arrays of numbers
	* Return Value
		Smallest value

floor(num)
	* Description
		Returns the largest integer less than or equal to the number (rounds down).
			Ex) floor(2.7) // 2
			Ex) floor(-2.7) // -3
	* Parameters
		num - Number
	* Return Value
		Integer

ceil(num)
	* Description
		Returns the smallest integer greater than or equal to the number (rounds up).
			Ex) ceil(2.1) // 3
			Ex) ceil(-2.1) // -2
	* Parameters
		num - Number
	* Return Value
		Integer

round(num)
	* Description
		Returns the number rounded to the nearest integer.
			Ex) round(2.5) // 3
			Ex) round(-2.5) // -2
	* Parameters
		num - Number
	* Return Value
		Integer

hypot(x, y)
	* Description
		Returns the length of the hypotenuse (square root of x*x + y*y).
			Ex) hypot(3, 4) // 5
	* Parameters
		x - Number
		y - Number
	* Return Value
		Length of the hypotenuse

# String API (string.pg0)
Can be used with the following import statement. 
	#import("lib/string.pg0")

trim(str)
	* Description
		Trims the front and back of a string.
		The characters to be trimmed are whitespace characters such as spaces (" "), tabs ("\t"), line breaks and full-width spaces (the same as JavaScript's trim).
	* Parameters
		str - String to be trimmed
	* Return Value
		Trimmed string

to_lower(str)
	* Description
		Converts English strings to lowercase.
	* Parameters
		str - String to be converted to lowercase.
	* Return Value
		String converted to lowercase

to_upper(str)
	* Description
		Converts English strings to uppercase.
	* Parameters
		str - String to be converted to uppercase.
	* Return Value
		String converted to uppercase

str_match(ptn, str)
	* Description
		Use wildcards to compare strings.
		Match any multi-character string with "*", match any single character with "?".
		The comparison is case-insensitive.
	* Parameters
		ptn - Pattern from which to compare (specify wildcard here)
		str - String to be compared
	* Return Value
		Returns 1 if a match is found, 0 if no match is found.

substring(str, begin, length = -1)
	* Description
		Extract substrings from a string.
	* Parameters
		str - String to be extracted
		begin - Start index
			(Negative numbers are indexed from the end of the string)
		length - Length to be extracted (negative numbers will be the length to the end)
	* Return Value
		Extracted substrings.

in_string(str, search, from = 0)
	* Description
		Searches for the position of a specified string within a string.
	* Parameters
		str - String to search in
		search - String to search for
		from - Index to start the search (a negative number is treated as 0).
	* Return Value
		Returns the index of the found string. If not found, returns -1.

split(str, separator)
	* Description
		Split a string with a delimiter string.
	* Parameters
		str - String to be split
		separator - delimiter string (an empty string splits into single characters)
	* Return Value
		Array containing the divided strings.

# Input/Output API (io.pg0)
Can be used with the following import statement. 
	#import("lib/io.pg0")

println(line)
	* Description
		One line output to standard output.
	* Parameters
		line - The string to be output.
	* Return Value
		0

wait(ms)
	* Description
		Pauses the program for the given number of milliseconds.
		Does not need the screen library; the stop button interrupts it.
	* Parameters
		ms - Time to wait (milliseconds)
	* Return Value
		0

saveValue(key, value)
	* Description
		Saves values.
		The value to be saved can be a number, a string or an array.
		The value is saved in the web browser.
		The values are initialised if the script save location is changed.
			New file - Common area.
			Local file - Saves the local filename as a key.
			Online file - Saved with the online cid as key.
	* Parameters
		key - Key
		value - Value to be saved.
	* Return Value
		0

loadValue(key)
	* Description
		Loads the saved value.
	* Parameters
		key - Key
	* Return Value
		Saved value. 0 when nothing is saved.

removeValue(key)
	* Description
		Remove saved values.
	* Parameters
		key - Key
	* Return Value
		0

get_clipboard()
	* Description
		Get text from the clipboard.
	* Parameters
		None
	* Return Value
		Clipboard text

set_clipboard(text)
	* Description
		Set text on the clipboard.
	* Parameters
		text - Text to be set on the clipboard.
	* Return Value
		Returns 1 on success, 0 on failure.

# Network API (net.pg0)
Can be used with the following import statement. 
	#import("lib/net.pg0")

People who have the same program open (the same program saved online, with the same cid) can send values to each other. Use it for games played online against each other.
* It works only in a program saved online (saving gives the program a cid).
* Only copies of the program with the same cid are connected; never other programs.
* The server stores nothing: a value sent only reaches the other people in the room.
* When the program ends (including the stop button), it leaves the room.
* The size and number of values sent are limited (by default up to 16 KB each and 60 a second). What goes over is not sent, and a notice is shown in the console.

Example: two people send each other a position
	#import("lib/net.pg0")
	#import("lib/io.pg0")
	me = netJoin()
	if (me == 0) {
		println("Could not connect")
		exit
	}
	while (netCount() < 2) {
		wait(100)
	}
	x = 100 * me
	netSend({"x": x})
	while (netAvailable() == 0) {
		wait(100)
	}
	m = netReceive()
	println("x of player " + m["from"] + " is " + m["data"]["x"])

netJoin(room, players)
	* Description
		Enters a room, and waits until it is in the room or has failed (10 seconds at most).
		It is connected with the people of the same cid in the room of the same name.
		Without a room name (or with ""), it enters a room that is not full yet by itself.
		Once such an automatic room has been full, nobody else enters it.
		With a room name agreed beforehand, friends can enter the same room.
		A full room, or a room closed with netClose(), cannot be entered.
		Only the program as saved online can enter (save the changes that are not saved, or open the program
		again when a newer version has been saved, then run it again).
		When it is already in a room, it leaves that room first.
		In the web version, when the connection goes (a phone that switched to another app) and comes back
		within 60 seconds (a setting of the server), it is back in the room with the values sent meanwhile,
		and the others do not notice; otherwise netId() becomes 0.
	* Parameters
		room - Room name (optional, up to 32 characters)
		players - Number of players of the room (2 when omitted, 2 to 8). The value of the person who made the room is used.
	* Return Value
		Your player number (1, 2, ...), or 0 when it could not enter.
		Numbers are given in the order of entering: the smallest number that is free.
		When it could not enter, the reason is shown in the console.

netLeave()
	* Description
		Leaves the room.
	* Parameters
		None
	* Return Value
		0

netClose()
	* Description
		Closes the room: nobody else can enter it any more.
		Call it when the game starts, and nobody comes in part-way through.
		Free seats, and seats left later, are not offered again.
		Anybody in the room may call it, and it cannot be undone.
	* Parameters
		None
	* Return Value
		1 when the room was closed, 0 when not in a room.

	Example: a game for 2 to 4 people that player 1 starts once 2 or more have come
		me = netJoin("", 4)
		if (me == 1) {
			while (netCount() < 2) {
				wait(100)
			}
			netClose()
			netSend("start")
		}

netId()
	* Description
		Gets your player number.
	* Parameters
		None
	* Return Value
		Your player number. 0 when not in a room (also after the connection was lost).

netRoom()
	* Description
		Gets the name of the room. A room entered automatically has a name starting with "auto-".
	* Parameters
		None
	* Return Value
		The room name. "" when not in a room.

netRooms()
	* Description
		Gets the rooms of this program (the same cid), for a lobby where a player picks a room to enter.
		It can be called in a room or out of one, and waits for the answer of the server.
		The rooms come in the order they were made (oldest first), up to 500. A room nobody is in is gone.
		Every call asks the server, so call it every few seconds rather than every frame.
	* Parameters
		None
	* Return Value
		An array with {"room": name, "count": people, "max": seats, "closed": 0 or 1} for each room.
		{} when there is no room. 0 when the server cannot be reached.

	Example: enter a room that has a free seat
		rooms = netRooms()
		if (isType(rooms) != 3) {
			println("Could not connect")
			exit
		}
		for (i = 0; i < length(rooms); i++) {
			r = rooms[i]
			if (r["count"] < r["max"] && !r["closed"]) {
				me = netJoin(r["room"])
				break
			}
		}

netCount()
	* Description
		Gets the number of people in the room, you included.
	* Parameters
		None
	* Return Value
		The number of people. 0 when not in a room (also after the connection was lost).

netPlayers()
	* Description
		Gets the player numbers of the people in the room.
	* Parameters
		None
	* Return Value
		Array of player numbers, smallest first. Example: {1, 2}

netSend(value, to)
	* Description
		Sends a value: a number, a string or an array. It does not come back to you.
	* Parameters
		value - The value to send
		to - Player number to send it to (everybody else in the room when omitted)
	* Return Value
		1 when it was sent, 0 when it could not be (for example when not in a room).

netAvailable()
	* Description
		Gets the number of values received and not taken with netReceive() yet.
	* Parameters
		None
	* Return Value
		The number of values (1000 at most; past that the oldest are dropped).

netReceive()
	* Description
		Takes the oldest received value.
	* Parameters
		None
	* Return Value
		Array {"from": player number of the sender, "data": the value sent}.
		0 when nothing has been received.

netLast(player)
	* Description
		Gets the last value received from the given player, whether or not it was taken with netReceive().
		In a game where everybody keeps sending their position, this alone tells what the others are doing.
	* Parameters
		player - Player number
	* Return Value
		The last value received. 0 when nothing has come from that player yet, or when they left the room.

--
Copyright (C) 1996-2026 by Ohno Tomoaki. All rights reserved.
    WEB SITE: https://nakka.com/
    E-MAIL: [email protected]