Mappack Nailed Lua

#Nailed Lua

Lua is the way to make your games more server-friendly and easier to manage. The easiest way to get started is to go to the terminal, accessible with the /terminal command.

##Terminal

Once you open the terminal, you'll see there are two tabs open, a tab named shell and a tab named game manager. The first is a normal shell, with some commands. The second tab is the tab where you can start your game, and where you can see some debug info about the game you are playing and have played.

##Shell Commands

There are several shell commands you can use to interact in the lua command line. Here they are:

command + arguments	explanation
cp <file> <destination>	Copies file 'file' to the destination, relative to the current path.
cd <destination>	Go to the destination folder. .. can be used for the map upstream.
bg [command]	Opens a new tab that will run the command you used as an argument. If no command was given after bg, it opens another shell.
edit <file>	Opens file 'file' to edit. After opening the file, you can use the control key to save and exit the editor.
<file>	Runs the file as lua code. This will not work if it is not valid lua.

##Lua Programming

Nailed uses the lua scripting language to make games more interactive. It contains various possibilities, which you can find at the official lua tutorial

###Nailed added functions

Nailed gives every lua program two extra objects, from who several others can be extracted: the map object and the scoreboard object.

####Map

The map is the main source of getting player- and team-objects. The object is directly accessible by using map in your program. Possible functions include:

function	explanation
.sendNotification(<string>)	Sends notification <string> to all players in the map.
.sendChatComponent(<string>)	Sends the chatcomponent <string> to all players on the map. Notice it has to be a valid Minecraft chatcomponent, and valid JSON.
.sendChat(<string>)	Sends the message <string> to the map chat.
.watchUnready(<bool>)	Whether the game should stop if one of the teams gets unready.
.winnerInterrupt(<bool>)	Whether all lua threads should stop if the game has announced a winner.
.getPlayers()	This function returns all the players in the map.
.getTeams()	This function returns all the teams in the map.
.forEachPlayer(function(p) ... end)	This function executes the function given over every player p in the map. 'p' is the variable the player is stored in in that function.
.forEachTeam(function(t) ... end)	This function executes the function given over every team t in the map. 't' is the variable the team is stored in in that function.
.getTeam(<teamname>)	Returns the team with name <teamname>
.setDifficulty(<difficulty>)	Sets the difficulty of the map. These values count as difficulties: 0, 1, 2, 3
.sendTimeUpdate(<string>)	Sets the message at the countdown timer to <string>.
.setTime(<value>)	Sets the time of the map to <value>.
.setWinner(<player/team>)	Sets the winner to the player or team given as an argument.
.enableStat(<statname>)	Enables the stat <statname>.
.spreadPlayers()	Spreads the player around the map to the random spawn points given in the mappack.cfg
.tpAllToLobby()	Teleports all players to the lobby world.
.remove()	Doesn't do anything yet.
.recycle()	Doesn't do anything yet.
.hasMappack()	Returns true if it has a mappack.cfg, otherwise returns false.
.onStarted()	Starts the gamescript.lua.
.onStopped(<bool>)	I don't know what this does. No, honestly, I don't.

#####Player

The player is the most extended object in Nailed, and has various functions to it.

function	explanation
.getUsername()	Returns a string with the username of the player
.getTeam()	Returns the team the player is in, nil if the player is in none.
.clearInventory()	Clears the inventory of the player.
.setSpawn(<x>, <y>, <z>)	Sets the spawn to the x-, y- and z-coordinates.
.setGamemode(<gamemode>)	Sets the gamemode of the player to <gamemode>.
`.setHealth(	Sets the health to <value> health points. Note health is counted in half hearths, and not whole hearts.
.setFood(<value>	Sets the food level to <value> food points. Note food points are counted in half nuggets, and not whole nuggets.
.setExperience(<value>)	Sets the experience level of a player to <value>. Note that these are not levels
.getType()	Returns "player"
.freeze(<bool>)	Whether the player should be able to move or not. Turning is still allowed.
.sendChatComponent(<string>)	Sends the chatcomponent <string> to the player. Notice it has to be a valid Minecraft chatcomponent, and valid JSON.
.sendChat(<string>)	Sends the message <string> to the player's chat.
.addPotionEffect(<id>, <duration> [, <amplifier>])	Gives the player an potion effect of the given proportions.
.removePotionEffect(<id>)	Removes the potion effect whose id is <id> from the player.
.sendTimeUpdate(<string>)	Sets the value of the timer in the top-right corner to <string>
.giveItem(<name>, <amount> [, <meta>])	Gives the specified items <amount> times to the player.
.setTeam(<teamname>)	Sets the team of the player to the team given

#####Team

The team is ... lorem ipsum

function	explanation
.getName()	Returns the name of the team.
.getPlayers()	Returns all the players that are member of that team.
.forEachPlayer(function(p) ... end)	This function executes the function given over every player p in the map. 'p' is the variable the player is stored in in that function.
.setSpawn(<x>, <y>, <z>)	Sets the spawn of all players in the team to <x>, <y>, <z>.
.getType()	Returns "team"
.getID	Returns the ID of the team.

####Scoreboard

Nailed implements it's own scoreboard system, since the native (Minecraft) version doesn't have a lot of possibilities for editing the values/getting events.

These functions are implemented on the scoreboard:

function	explanation
.getObjective(<name>)	Returns the objective with the name <name>, and it will create this objective when not already created.
.getTeam(<name>)	Returns the team with the name <name>, and will create this team when not already created.
.setDisplay(objective, <place>)	Sets the score values for the players to visible at the given place. This place is one of these: sidebar, belowname or list.

#####Objectives

The objective object is the object to keep track of player scores and values, and have to be kept for more than just one game.

The objective has these functions added to it:

function	explanation
.getId()	Returns the ID of the objective. Unique value in the whole map.
.getDisplayName()	Returns the display name of the objective. Does not have to be unique.
.setDisplayName(<string>)	Sets the display name of the objective to <string>. This does not have to be a unique value.
.getScore(<playername>)	Returns the objective value of the given player.
.setScore(<playername>, <value>)	Sets the objective value of the given player to <value>.
.addScore(<playername>, <value>)	Adds to the score of the given player on that objective.

NOTE: The HAS to be a string! If you use an player instance, it WILL fail.

#####Teams

Notice that these teams DO differ from the map teams. Currently there are not many differences, but the difference will get bigger.

The scoreboard teams do have the following functions attached:

function	explanation
.getId()	Returns the ID of the team. This is an unique value.
.getDisplayName()	Returns the display name of the team.
.setDisplayName(<name>)	Sets the display name of the team to <name>
.getType()	Returns the type of the team.
.getPrefix()	Returns the prefix of the team.
.setPrefix(<value>)	Sets the prefix of the team to <value>
.getSuffix()	Returns the suffix of the team.
.setSuffix(<value>)	Sets the suffix of the team to <value>
.isFriendlyFire()	Returns boolean value, true if friendly fire is on, otherwise it returns false.
.setFriendlyFire(<bool>)	Sets friendly fire to <bool>
.isFriendlyInvisiblesVisible()	Returns boolean value, true if friendly invisibles are visible, otherwise it returns false.
.setFriendlyInvisiblesVisible()	Sets friendly invisibles visibility to <bool>
.addPlayer(<player>)	Adds player <player> to the team.
.removePlayer(<player>)	Removes player <player> from the team.
.getPlayers()	Returns the players currently available in the team.
.forEachPlayer(function(p) ... end)	This function executes the function given over every player p in the map. 'p' is the variable the player is stored in in that function.