HELP.txt

Command reference for the IRC bot Nyisorn
Written by Krock <mk939@ymail.com>

Table of contents: (Use the search function Ctrl+F)
* Lua commands
	- Calculations
	- Function calls
	- External function calls
	- Function list
* Other commands
* The cheat game
	- Theory of the game
	- Joining and leaving
	- Cards on the stack
	- Tricking the players
	- Queens
	- End of the game

Main help channel: irc.rizon.net/#nimg_lobby
Notice: Most of the commands work in the private chat aswell - Please don't spam the main channel.


 Lua commands
==============
You can execute Lua scripts with following long prefix
> $lua <code here>
or with the short variant
> $ <code here>

To return a text, it would be
> $ return "a text"

Define and output a variable:
> $ local msg = "Hello World"; return msg


 Calculations
--------------
The math operations are the same as in other programming languages too.
To calculate something, use the operations + - * / or any of the builtin math functions.
Get a complete list of the builtin functions here: http://lua-users.org/wiki/MathLibraryTutorial

> $ return (300*2)/0.4*math.pi


 Function calls
----------------
By default, there are some functions you can call directly without having to do anything special.

If you want to get all links which are stored in the bot, use this command:
> $ link("list")
The braces tell our Lua intepreter to call a function. The string "list" is an argument
that is submitted to the function.

There might be more arguments required, for the math.round function, as example.
Use Lua to round a number and show 1 digit after the decimal point:
> $ return math.round(12.34567, 1)

See section "Function list" to see them all.


 External function calls
-------------------------
Sometimes it's good to know if there are other things that can be used. For this,
 check out the available Lua modules/scripts that can be included to the bot.
> $ help()

Call the special Lua function "dofile" to include a file to
your command to call a function inside the loaded module.
> $ noobgen.generate(2)


 Function list
---------------
Functions of all added modules with their explanation.
All asterisk (*) marked functions do not require a "$ return .." to output the text.

List of additional modules:
	- <morse.lua> Convert text to morse code and back again
	- <noobgen.lua> Generate noobish text
	- <quotes.lua> Add and read quotes


# Default functions: (automatically loaded)
	adduser("<nick>", "<group>")
		^* Adds a person of the current channel to any group

	remuser("<nick>", "<group>")
		^* Removes a person of the current channel from any group

	coin([n])
		^* Returns the number of heads after flipping a coin n (or 1) times

	decide("<text>")
		^* Returns either "Yes", "No" or "Maybe" on any question

	executionTime()
		^* Returns the time it took to execute the script

	fire()
		^* Fires a shot in the russian roulette. 1 / 6 chance to get killed

	help()
		^* Reference to this file

	link("list") -> link("<link name>")
		^* Returns a pre-defined text for the given link name

	paperfold(height, [thickness])
		^* Folds a piece of paper X times until it reaches the specified height in meters
		^ height: number or "<formatted number>"
		^ thickness: number or "<formatted number>", defaults to 1 mm

	sell("<item>")
		^* Sells the item for a random price


# Extended helper functions: (automatically loaded)
	dump(object)
		^ Analyzes and outputs a table and its contents as a string

	fromFancy("<formatted number>")
		^ Formats ugly number to fancy ("1k" -> 1000, "1 m" -> 0.001)

	toFancy(number)
		^ Converts fancy number to ugly (1000 -> "1k", 0.001 -> "1m")

	getUserObject("<name>")
		^ Searchs a currently online user in the channel (case insensitive)
		^ Returns { nick=?, hostmask=? } or nil if not found

	math.round(number, [digits])
		^ Rounds the number
		^ digits: Optional, describes the decimal digits

	math.sign(number, [tolerance])
		^ Gets the sign of a number
		^ tolerance: Optional, must be a positive number

	my_string_variable:split("<delimiter>")
		^ Splits a string into an array, using the delimiter character(s)

	my_string_variable:trim()
		^ Removes beginning and tailing spaces

	percent(number, ["<text>"])
		^* Outputs a by 100 multiplicated number (0.521431, "average" -> "52.14% average")

	table.copy(table)
		^ Copies a table to remove its reference

	Complex([real], [imaginary])
		^ Creates a new complex calculating class
		^ real, imaginary: Optional, will be set to zero otherwise
		:add(real, imaginary)
		:add(Complex_object)
		:addPolar(length, angle)
			^ Adds polar value to the real and imaginary axis (degrees) [buggy!]
		:addReal(amount)
		:addImag(amount)
		:length()
			^ Length of the polar hypotenuse / absolute value
		:angle()
			^ Angle in the polar system (degrees)
		:tostring()
		:topolar()


# Functions in karma.lua:
	karma.credits()
		^* Outputs the credits of the current module

	karma.up("<nickname>")
		^* Adds 1 karma point to the specified person (requires authentification)
		^ nickname: A person that is present in the current channel (case insensitive)

	karma.get("<nickname>")
		^* Gets the karma of the specified person (case insensitive)


# Functions in morse.lua:
	morse.credits()
		^* Outputs the credits of the current module

	morse.toText("<morse code>")
		^* Converts morse code into readable text

	morse.fromText("<text>")
		^* Converts readable text into morse code


# Functions in noobgen.lua:
	noobgen.credits()
		^* Outputs the credits of the current module

	noobgen.generate([amount sentences])
		^* Generates noobish sentences, default: 3
		^ amount sentences: Optional, numeric value from 1 to 6


# Functions in quotes.lua:
	quotes.credits()
		^* Outputs the credits of the current module

	quotes.add("<text>")
		^* Adds a quote to the database (requires authentification)

	quotes.get([identifier])
		^* Gets a quote by index (number) or by keyword (string)
		^ identifier: Optional, a random entry will be shown

	quotes.remove(index)
		^* Removes one of your quotes


 Other commands
================
These commands do not depend on any Lua skills and can be used like any other regular bot command.
Note: Commands like "$uno p y 4" can be abbreviated to "$p y 4" until you leave the game.

$c <text>
	^ Colorizes the text

$help
	^ Returns the available commands of the bot (only partially helpful)

$tell <nick> <text>
	^ Tells the nick your text when (s)he joins a channel where the bot is present
	^ Detection sensivity: Nicknames can have 1 typo per 4 characters in the name

$join <channel>
$part <channel>
	^ Bot admin commands. Change config file to make this persistent.


 Superior UNO Game
===================
Q: Why superior?
A: Because it offers more than UNOBot

$uno join <mode>
	^ mode: optional, hexadecimal value of UNO modes to set (m_SuperiorUno.cs)

$uno leave
$uno deal

$uno top
	^ Outputs the last played cards and your cards.

$uno p <color> <face>
	^ color: r, g, b, y
	^ face: 0 .. 9, S, R, W or WD4

$uno d
	^ Draw one card or the "draw count" based on played D2 and WD4 cards

$uno elo <nick>
	^ Outputs the ranking of a specific player


 The Cheat Game
================
This game is a turn-based cards game all about lying and and tricking your opponents.

Win condition: get rid of ALL your cards - no matter how it's done
Game duration: up to 30 minutes

Much more information here: https://en.wikipedia.org/wiki/Cheat_%28game%29


 Theory of the game
--------------------
By default there is a total of 35 cards which will be dealt evenly upon game start:
	* four of each type (6, 7, 8, 9, 10, J, K, A)
	* three queens to prevent players from winning

Cards must be placed onto the game central stack which only allows one kind of card.
A turn in-game looks as follows:

	<BotName> [LGame] Main card: [A], Stack height: 2, Next player: XxFooBar123xX
	-Notice-  Your cards: 1[A] 2[K] 3[10] 4[A] 5[8]
	_____________________ ^ Card index ____ ^ Card type

The main card specifies which kind of card that should be added on top of the stack.
Use your card's index (black number) to play the corresponding card from your hand.

This way you can either lie:
	> $lgame add A 3
Or tell the turth: (example with multiple cards)
	> $lgame add A 1 4

Afterwards your opponent can decide whether to check your cards or to continue.
	> $lgame check
	If your placed cards were correct: the opponent takes the entire stack.
	If your placed cards were incorrect: you take the entire stack.

Four similar cards (example: A A A A) will automatically be discarded (like in the quartet game).

As soon the stack was taken (after each check), the next player can chose the next
card that is used as "main card". Example:
	> $lgame add K 5

The game continues until there are only two players left.


 Start a game
--------------
Use following commands to join or leave:
	> $lgame join
	> $lgame leave

As soon there are at least three players, the game may begin:
	> $lgame start

The first player starts with an empty stack, thus they may start a new one:
	Main card = 9, taken from index 4 of the hand
	> $lgame add 9 4


 Tricking the players
----------------------
Somewhen there are 7 cards on the stack and everybody says they're a king card.
This is the point where they might start to lie. If you don't believe the previous player, simply use
> $lgame check
..and the last placed card(s) will be checked whether they are correct main cards or not.

If they're actually correct, you get the complete stack and the next player can start a new stack.
In the other case, if one or more top cards are not correct, the complete stack gets sent to the previous player
 and you can start with a new stack. (This is what you should try to reach!)


 Queens
--------
In this variant of cheat game, there's a bad card type: the queen.
Whenever you have 4 similar cards, they're automatically discarded by the bot.
But there are only three queens (red marked whenever you see your cards), this means they can not be discarded.
The best method is to get a queen somehow to a player with less cards by lying,
so they can not win the game until the queen is away.


 End of the game
-----------------
You win when you have no cards left and the next player did his move.
The best strategies to reach this are:

- With two cards:
	Put down a fake card first and the real one in round two.
	You will have no cards left and the next player cannot prevent you from winning.

- With similar cards:
	Put down a fake card and the other similar cards in the 2nd round, same result as above.

- Annoy the players:
	If they don't believe you anything anymore, simply put one correct card.
	Repeat this until they won't check all your cards anymore. Find the perfect balance!

- Manipulation with communication:
	Words help - or not. Just try to confuse the people with sentences like
	"Oh shit! Wrong card" or "Oops, how can I place another card instead?".