[ tamius.net | &DnD — magic++ ]
« back to the first page


This class contains properties, constants and functions that are relevant to the player’s character.

All NPCs are an instance of class Player (most of this also applies to creatures and monsters). If you have an object that represents a NPC or a creature, you can call all public functions, but you can’t access the properties, constants and private functions. If you successfully assume control, you have full access.



Player.D<number> — Player’s dice. For example: Player.D20 is player’s d20, Player.D6 is player’s d6 … And so forth for every dice. Player object may contain non-standard dice as well.

Body parts:

Player.RIGHT_HAND — Player character’s right hand
Player.LEFT_HAND — Player character’s left hand
Player.RIGHT_LEG — Player character’s right leg
Player.LEFT_LEG — Player character’s left leg.
Player.HEAD — Player character’s head

In general, you can refer to any visible body part using a call, formatted like this:

Player.<name of body part in all caps>

This excludes fingers. Fingers are stored in Player.RIGHT_HAND. (similar for fingers on left hand and feet). Alternatively, you can use Player.RIGHT_HAND.FINGERS[i], where 0 <= i <= 4. FINGERS[0] is thumb, FINGERS[4] is the little finger.

Note regarding finger indexes: if player’s character belongs to a race that has !=5 fingers on each hand, the max index is equal to – 1. FINGERS[0] in that case refers to the innermost finger.

If the character lost a finger, the max index doesn’t change. Instead, the lost finger is being treated as null (for example, if a character lost their index finger, FINGERS[INDEX_FINGER] (or: FINGERS[1]) returns NULL).


NOTE: some of the following functions require player to roll a D20 in order to determine success. Much of that can be left to DM's discresion, though.

private allowAccess(player)

You can use this function to allow another entity to control your character without the need for them to use a private key. NOTE: this method is private – you can’t call it for other characters.

public assumeControl(privateKey)

Assume control of a character character.

privateKey — a string of symbols that allows you to control the character.

This function requires line of sight between the caster and the object to succeed.

Returns 0 on success.

Returns -1 on failure.

Example use:

Object target = getObject(Player.getPointingDirection(Player.RIGHT_HAND));
target.assumeControl("key goes here");

Once you successfully assume control of a character, you can access all the private functions of that character.

private attack(weapon, dice, target)

Attacks target using weapon. Uses ’dice’ to determine damage. You must call ’roll()’ before using this function.

Returns 0 on success.

Returns -1 on general failure.

Returns -2 if player wants to attack using a weapon that’s not in their hands.

private drawWeapon(weapon)

Draws an equipped weapon. Returns ’0’ on success. Returns -1 if weapon is not equipped.

private drop(item)

Drops the item on the ground. Item can be in inventory, equipped or in hand.

private equipWeapon(weapon)

Equips item in inventory.

private exec("commands")

Executes arbitrary commands as current player (if possible, enables casting spells as a character you control, but every command in the command string takes twice as long to execute due to the overhead. If you can execute 6 commands per turn, you can only execute three commands with exec()).

private fly()

If character has the ability to fly, this function switches them to the ’fly’ mode.

NOTE: most creatures need to fly a certain distance in order to avoid stalling and falling down. If a creature starts the round in a flying state, they must move at least as far as their slowest fly speed. (Not applicable to creatues with hover ability).

public getLocation()

Returns current location of the player, relative to the world.

public getPointingDirection(limb|finger|item|weapon)

Returns the direction in which the character is pointing with something. Accepts limb, finger, item or weapon as argument.

private hasAdvantage()

Returns ’true’ if player has an advantage. Returns ’false’ otherwise.

private hasDisadvantage()

Returns ’true’ if player has disadvantage. Returns ’false’ otherwise.

public isFlying()

Returns true if the character is currently in a flying state. Returns false if not.

public isSwimming()

Returns true if the character is currently swimming. Returns false if not.

public inWater()

Returns true if the character is currently in water. Returns false if not.

private land()

If character is flying, use this command to land.

private move(x, y)

x: distance front/back of the player

y: distance left/right of the player

’x’ and ’y’ can’t be smaller than the movement resolution supported by the map (usually 5).

Moves player relative to the player’s current position, in a straight line.

Returns 1 if successful.

Returns 0 if there is an object blocking the path.

Returns -1 if player fell into a hole.

When calling this function, the character can move as far as their speed allows. This instruction is not complete until the move is finished. If the character hasn’t finished their move by the end of their turn, the instructions that come after the move() call aren’t processed until the turn in which the move is finished.

private moveTo(x, y)

Same as move(), except it takes a position relative to the world rather than position relative to the player.

private pickItem(item)

Picks an item lying on the ground (within characters’ grabbing range). Returns ’0’ on success, -1 on failure.

private roll(Dice)

Returns a value between dice’s minimum and maximum values.

Returns -1 if the dice rolls off the table.

In case of advantage/disadvantage, the function rolls the dice twice and returns the proper value automatically.

private say(message)

Makes character say something (whatever the variable ’message’ contains). ’message’ must be a string. This function doesn’t count as an instruction (you can use it for free), though the DM may limit the length of a message and how many times per turn you’re allowed to use it.

private stash(item)

Puts the item currently in character’s hands in inventory.

private throw(item, target|location)

Makes character throw the item at target or location (specify one). Item must be in player's hands. Requires player to roll a d20.

private throw(weapon, dice, target|location,)

Makes character throw the weapon at target or location (specify one). Player must hold the weapon they're about to throw. Dice is a weapon die. Requires player to roll a d20.

private unequipWeapon(weapon)

Puts currently equipped weapon in inventory.

private useItem(item, [additionalStuff])

Uses an item. Item must be in characters’ hands, equipped, in inventory, or otherwise ready to be used by the player. Returns 0 on success, -1 on failure.

private useSkill(skillName, [dice, additionalObjects])

Uses a skill a character can use. SkillName is the name of the skill. You must call ’roll(D20)’ before using a skill. If the skill deals damage, you must provide a dice that determines the base damage. If skill uses other objects, you must also pass them to the function.

Returns 0 on success, -1 on failure.