skinsdb/API.md

Skinsdb Interface

skins.get_player_skin(player)

Return the skin object assigned to the player. Returns default if nothing assigned

skins.assign_player_skin(player, skin)

Check if allowed and assign the skin for the player without visual updates. The "skin" parameter could be the skin key or the skin object Returns false if skin is not valid or applicable to player

skins.update_player_skin(player)

Update selected skin visuals on player

skins.set_player_skin(player, skin)

Function for external usage on skin selection. This function assign the skin, call the skin:set_skin(player) hook to update dynamic skins, then update the visuals

skins.get_skin_format(file)

Returns the skin format version ("1.0" or "1.8"). File is an open file handle to the texture file

skins.get_skinlist(assignment, select_unassigned)

Obsolete - use get_skinlist_for_player() or get_skinlist_with_meta() instead

skins.get_skinlist_for_player(playername)

Get all allowed skins for player. All public and all player's private skins. If playername not given only public skins returned

skins.get_skinlist_with_meta(key, value)

Get all skins with metadata key is set to value. Example: skins.get_skinlist_with_meta("playername", playername) - Get all private skins (w.o. public) for playername

skins.register_skin(path, filename)

Registers a new skin based on the texture file path specified by path and filename.

• path (string): points to the parent directory of the texture filename. Generally, this should be in the format mymod.modpath .. "/textures".
• filename (string): full file name, without any path specifications. The file name must adhere to one of the accepted naming formats.

Note: this function takes the following files into consideration:

1. <path>/<filename> (required)
   • Main skin texture
2. <path>/<filenamestem><separator>preview.png (optional)
   • Pre-generated preview image
3. <path>/../meta/<filenamestem>.txt (optional)
   • Metadata regarding the skin

Return values:

• On failure: false, reason
  • reason (string): human readable reason string (similar to io.open errors)
• On success: true, key
  • key: unique skins key for use with e.g. skins.get(key) for subsequent fine-tuning of the skin registration.

skins.new(key, object)

Create and register a new skin object for given key

• key: Unique skins key, like "character_1"
• object: Optional. Could be a prepared object with redefinitions

skins.get(key)

Get existing skin object

HINT: During build-up phase maybe the next statement is usefull

local skin = skins.get(name) or skins.new(name)

Skin object

skin:get_key()

Get the unique skin key

skin:set_texture(texture)

Set the skin texture - usually at the init time only

skin:get_texture()

Get the skin texture for any reason. Note to apply them the skin:set_skin() should be used

Could be redefined for dynamic texture generation

skin:set_hand(hand_node)

Set the hand node to be used with this skin

skin:set_hand_from_texture()

Register and set hand node based on skin texture. Uses different model depending on get_meta("format") ("1.0" or "1.8") Only works on mod load

skin:get_hand()

Get hand node. Returns ItemStack

skin:set_preview(texture)

Set the skin preview - usually at the init time only

skin:get_preview()

Get the skin preview

Could be redefined for dynamic preview texture generation

skin:set_skin(player)

Hook for dynamic skins updates on select. Is called in skins.set_player_skin() In skinsdb the default implementation for this function is empty.

skin:apply_skin_to_player(player)

Apply the skin to the player. Called in skins.update_player_skin() to update visuals

skin:set_meta(key, value)

Add a meta information to the skin object

Note: the information is not stored, therefore should be filled each time during skins registration

skin:get_meta(key)

The next metadata keys are filled or/and used interally in skinsdb framework

• name - A name for the skin
• author - The skin author
• license - THe skin texture license
• assignment - (obsolete) is "player:playername" in case the skin is assigned to be private for a player
• playername - Player assignment for private skin. Set false for skins not usable by all players (like NPC-Skins), true or nothing for all player skins
• in_inventory_list - If set to false the skin is not visible in inventory skins selection but can be still applied to the player
• _sort_id - Thi skins lists are sorted by this field for output (internal key)

skin:get_meta_string(key)

Same as get_meta() but does return "" instead of nil if the meta key does not exists

skin:is_applicable_for_player(playername)

Returns whether this skin is applicable for player "playername" or not, like private skins