Character functions

From HEWIKI
Jump to: navigation, search

Contents

Character functions include the exposed and external functions related to character nodes.

See also

Player-handling

These are all server-side exposed functions.

Move Player to New Area

MovePlayer(movingPlayer as noderef, destinationArea as ID, destinationInstance as ID) as boolean

This server-side exposed function attempts to move the player to the new area. If the noderef is invalid, this function returns a value of FALSE (and may eventually trigger a script callback, stay tuned).

This function is used only by the travel script system, and should not be called outside of that system.

Once a player is moved, nothing else can be done to the player by the current script.

Main Page: Move_Player

Kick a player offline

KickPlayer(kickedPlayer as noderef, kickedPlayerID as ID, playerMessage as string, logMessage as string)

Server-side exposed function. Kicks the player offline, displaying playerMessage to them, and logging the event with whatever is in logMessage.

Main Page: Kick Player

Hide Other Characters (deprecated)

function HideOtherCharacters(hide as Boolean)

This function toggles a flag in the character command center part of the area, which makes it so that nobody can see anyone else while they are in the area. For example, in character creation area, this is used to present an illusion that nobody else is in the area.

Get list of online players

Main page: Online Players

function OnlinePlayers() as list of id

This function returns the list of players online in an area, or all players online if it is called at the world server level.

Find Player By Name

Main page: Find Player By Name

function FindPlayerByName(findName as string) as id

Gets the root node id of a player by their current character name. Only sees the players online at the area server level, or all players at the world server level.

Update Character Name

function UpdateCharacterName(character as noderef, newName as string) as boolean

Call this function only in the area where the character is loaded. Pass the node id of the character, not the account root id. Returns false if the name is in use, or the character is not online.

function GetPlayerName(accountRoot as noderef) as string

Given the account root, this function returns the name of the character the player has logged in. If the player has not selected a character, this returns the login name, ie SIMU-HAPPYPLAYER. This function only works at the world server level and in the area the player is in. If the player is not online, this function will return a null string.

An account root is a node of class _playerAccount that the player's characters are attached to.

Main Page: Get_Player_Name

Holding Area Functions

These functions only work in the Holding Area.

Select Character

Main page: Select Character

function SelectCharacter(accountRoot as noderef, characterNode as noderef)

This function should only work in the Holding Area. It picks one of the characters of an account.

The Holding Area is defined as Area #1. After initial logon, the World Server directs a new user to this area, so that they can select or create a character. If a character is deleted, this is also the area that the player is sent back to, to generate a new character. Each World has its own Holding Area.


Delete Character

See: Delete Character

Where Is Player?

Main page: Where Is Player

function WhereIsPlayer(character as id, area references id, instance references id) as boolean

Only functions on the world server. Given a player's ID, it fills out area and instance with the player's current location. Returns false if the player isn't online.


Visual Appearance Functions

The visual appearance functions are all client-side changes. Once you've used them, you must call

  SendModelUpdate()

to update the character settings that are stored on the server; otherwise, the next time your client receives a model update from the server, your character will revert to its previous state.

If you're unsure about what's referenced here, see Dynamic_Character_Primer for an intro.

Geometry Functions

For a reference, see Parts Files.

Division Functions

Division functions return divisions and slots in the order defined in the [Division] section of the .par file.

Fills a list with strings in the form "slotName:partName"

  GetDivisionStatus(charNode as noderef, divisionName as string, statusStrings as list of string)

Self-explanatory functions:

  GetDivisions(charNode as noderef, divisionNames as List of String)

Slot Functions

All slot functions are basically self-explanatory:

GetSlotsInDivision(charNode as noderef, divisionName as string, slotNames as List of String)
 
GetSlotKeyword(charNode as noderef, slotName as string) as string

GetSlotsInDivision returns slots in the order they're listed for the division in the .par file.

Part Functions

Returns false if unable to set partName.

  SetPart(charNode as noderef, slotName as string, partName as string) as boolean

Fills a list with part names that, given the current visual appearance of the charNode, could go in the given slot without visual artifacts.

  GetAvailablePartsForSlot(character as NodeRef, slotName as String, parts as List of String)

Straight listing of all specified parts for the given slot. This doesn't take into account anything that the character is wearing, and as such, some of the returned parts may be rejected if you attempt to call SetPart with them. Recommended mainly for building user interface.

  GetAllPartsForSlot(charNode as noderef, slotName as string, parts as List of String)
Note: Both GetAvailablePartsForSlot and GetAllPartsForSlot return parts in the same order that they're listed in the .par file (top-to-bottom).

The following functions provide access to parts and their keywords:

GetCurrentPartInSlot(charNode as noderef, slotName as string) as string
 
GetPartKeyword(charNode as noderef, slotName as string, partName as string) as string

Texture Functions

For reference on dynamic texture banks, see Technical:Dynamic_Texture_Banks.


Texture bank functions

Fills a list with status strings in the form "layerName:pieceName", where pieceName is the currently selected piece in the layer.

GetTextureBankStatus(character as NodeRef, bankName as String, bankStatus as List of String)

Self-explanatory:

GetTextureBanksForPart(character as NodeRef, slot as String, part as String, banks as List of String)

Layer functions

Layer functions guarantee that the order of the layers is top-to-bottom (that is, basemost layer first) according to the order of the layers laid out in the .dtb file.

Fills a list with the names of all child layers of a given piece.

GetPieceChildLayers(character as NodeRef, bankName as String, layerName as String, pieceName as String, layers as List of String)

GetLayersInTextureBank(character as NodeRef, bankName as String, layers as List of String)

GetLayersInTextureBank will populate the layers list with layer names concatenated with their index numbers (e.g.,"1:wizard hat base", "2:wizard robe base", "3:male face detail"). Other functions like GetAllPiecesInLayer and GetAvailablePiecesInLayer accept only the name of the layer (e.g.,"wizard hat base", "wizard robe base", "male face detail"). Thus the layer name must be parsed from the index these cases.

If GetLayersInTextureBank returns a blank list of layer names, ignore the bank.

GetLayerKeyword(charNode as noderef, textureBankName as string, layerName as string) as string

Piece functions

Fills a list with piece names of all of the pieces that are currently valid--given the visual appearance of the character--for layer with name layerName. Guarantees that pieces are in the same order that they are declared in the .dtb file, where the piece declared first is the first piece returned.

GetAvailablePiecesInLayer(character as NodeRef, bankName as String, layerName as String, pieces as List of String)

For the following two functions, whichColor is the palette index (pieces may have several colors, depending on the tinting type) to the list of palette names returned by GetPalettesForPiece. xCoordinate and yCoordinate are coordinates in the given palette, for sampling the color.

GetCurrentColorForPiece(character as NodeRef, bankName as String, layerName as String, pieceName as String, whichColor as Integer) as Vector3
 
SetTexturePieceColor(character as NodeRef, bankName as String, layerName as String, pieceName as String, whichColor as Integer, xCoordinate as Integer, yCoordinate as Integer) as Vector3
 
SetTexturePieceColorDirectly(character as NodeRef, bankName as String, layerName as String, pieceName as String, whichColor as Integer, color as Vector3) as Vector3

Note: Version 2.0 character skin layers use a linear blend of three weights based on position in the palette, in order to calculate skin color. Therefore, you should not use SetTexturePieceColorDirectly unless the components of the color you pass add up to one (i.e. (1,0,0) or (0,.5,.5) for (r,g,b)--alpha is ignored).

Self-explanatory:

GetPalettesForPiece(character as NodeRef, bankName as String, layerName as String, pieceName as String, fileNames as List of String)
 
GetCurrentPieceInLayer(character as NodeRef, bankName as String, layerName as String) as String
 
SetPiece(character as NodeRef, bankName as String, layerName as String, pieceName as String)
 
GetRandomPiece(character as NodeRef, bankName as String, layerName as String) as String
 
SetTexturePieceShininess(character as NodeRef, bankName as String, layerName as String, pieceName as String, shininess as Float)
 
GetTexturePieceShininess(character as NodeRef, bankName as String, layerName as String, pieceName as String) as Float
 
GetPieceKeyword(charNode as noderef, textureBankName as string, layerName as string, pieceName as String) as string

Skin functions

GetAllSkinOptions(character as NodeRef, options as List of String)
 
GetAllSkinBumpOptions(character as NodeRef, options as List of String)
 
GetCurrentSkinComponents(character as NodeRef, components as List of String)
 
GetCurrentSkinBumpComponents(character as NodeRef, components as List of String)
 
SetSkinComponent(character as NodeRef, componentToReplace as String, newComponentName as String)
 
SetSkinBumpComponent(character as NodeRef, componentToReplace as String, newComponentName as String)
 
GetSkinComponentBlend(character as NodeRef, componentName as String) as Float
 
GetSkinBumpComponentBlend(character as NodeRef, componentName as String) as Float
 
SetSkinComponentBlend(character as NodeRef, componentName as String, blendAmt as Float)
 
SetSkinBumpComponentBlend(character as NodeRef, componentName as String, blendAmt as Float)
 
SetSkinComponentBlends(character as NodeRef, componentBlendPairs as LookupList indexed by String of Float)
 
SetSkinBumpComponentBlends(character as NodeRef, componentBlendPairs as LookupList indexed by String of Float)

Use the following function to get a texture name for loading into a GUI control to display to the user:

GetSkinTextureName(character as NodeRef, componentName as String) as String

Face Race

GetFaceRace(character as NodeRef) as integer
 
SetFaceRace(character as NodeRef, race as integer)

For the following two functions, the blend amount range is [-1,1]:

BlendFaceRace(character as NodeRef, race as int, blendAmt as float)
 
GetFaceRaceBlend(character as NodeRef, race as int) as float

Face Shape

The below function returns a string that represents the keyword for the control, or an empty string if there was no keyword specified:

GetFaceShapeControlKeyword(character as noderef, ctrlId as integer) as string


The rest are pretty straightforward:

GetFaceShapeControls(character as NodeRef, controlNames as List of String)
 
GetFaceShapeControlValue(character as NodeRef, control as integer) as float
 
SetFaceShapeControlValue(character as NodeRef, control as integer, value as float)
 
GetFaceShapeControlKeyword(character as NodeRef, control as integer) as string

Miscellaneous face functions

RandomizeFace(character as NodeRef)


Body Morphing Functions

These use FaceGen and/or skeletal morphing technology:

GetBodyRaces(character as NodeRef, races as List of String)
 
GetBodyRaceBlend(character as NodeRef, race as String) as Float
 
SetBodyRaceBlend(character as NodeRef, race as String, raceBlendAmount as Float)
 
SetBodyRaceBlends(character as NodeRef, raceBlendPairs as LookupList indexed by String of Float)

GetBodyRaces doesn't return the races in any particular or guaranteed order.

SetBodyRaceBlends does no parameter checking, so it allows you to do some interesting (or unwelcome!) effects with negative blends, blends summing to greater than 1, etc.

SetBodyRaceBlend adjusts all of the other skeletons after applying the target skeleton's blend so that the blend weights of all skeletons add up to 1.0. This function's handy if you have a slider for each skeleton; simply call SetBodyRaceBlend on the changed slider's value and the engine will take care of automatically adjusting the other skeletons' blends. Make sure you then call GetBodyRaceBlend on each of the skeletons to get their updated values.

See Technical:Skeletal Morphing#Usage for more information on using these functions to modify a character's appearance.

Facial Morph Functions

Facial morphs are used for things like smiling, blinking, winking, and other facial expressions. Unlike the FaceGen functions above, facial morphs aren't saved between runs of HeroBlade, since they're just temporary changes.

Note: A character must be dynamic and have a facegen.dat file to be able to use these functions. See Technical:FaceGen Pipeline for more information on setting up a character to take advantage of FaceGen.

Facial morphs should be clamped between 0 and 1, although this isn't enforced in case you'd like to get some wacky effects using negative or large numbers.

GetFaceMorphs(character as NodeRef, morphNames as List of String)
 
GetFaceMorphValue(characters as NodeRef, morph as String) as Float
 
GetFaceMorphKeyword(characters as NodeRef, morph as String) as String
 
SetFaceMorphValue(character as NodeRef, morph as String, value as Float)

Style functions

Add style

  AddStyle(charNode as noderef, styleName as string) as boolean

Applies a style to the character identified by the GOM node

Remove style

  RemoveStyle(charNode as noderef, styleName as string);

Removes a style from the character

Get styles

  GetStyles(charNode as noderef) as string

returns:

"styletype:style,style,style,style|styletype:style,style,style"

Get style type count

  GetStyleTypeCount(charNode as noderef) as integer

Returns the number of style types



Get action marks for character

Returns a list of all ActionMarkNodes that the controlled character is inside of

  GetActionMarksForCharacter()

Miscellaneous Functions

Get World Space Bone Orientation

GetWorldSpaceBoneOrientation(character as NodeRef, boneName as String, position as Vector3, rotation as Vector3, scale as Vector3)

Gets the orientation of a bone of a character's skeleton in worldspace coordinates. Bone names can be derived from the skeleton.gr2 file for the character, using GrannyViewer or grn dump.

Look Up Player Account

LookUpPlayerAccountID(playerName as string) as ID

Takes a character name, and returns the ID that would reference the appropriate accountRoot. This function can be used for a player that is not in the current Area, or is not logged in.

Note: This function does cause a database hit, so should be used sparingly.

Main Page: Lookup_Player_Account_ID

Is Character Server Driven (deprecated)

This function is deprecated with the release of the Advanced Customizable Character Controller and you should instead check for the _ACCCServerControl and _ACCCClientControl classes.

IsCharacterServerDriven(char as noderef) as boolean

Returns TRUE if the character is currently being driven by server-specified waypoints.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox