The Faces module
The faces module is used for creating face images for comms screens.
Faces are based off of a set of image textures with a grid of cell images.
The set of images is defined in allFaceFiles.txt. This file defines a key name for the texture and an image in the data\graphics folder. Cells are 512x512 and the total images must be a valid DirectX12 pixel size.
This set of images can be extended with new textures added to allFacesFiles.txt
Face generation functions
The faces module has a set of functions to generate random faces for the base set of face image textures provided by Artemis Cosmos.
random_skaraanrandom_torgothrandom_kralienrandom_arvonianrandom_zimnirandom_terranrandom_terran_malerandom_terran_femalerandom_terran_fluid
=== "python"
self.face_desc = random_skaraan()
There are also function to make it easier to create specific faces by passing indexes to define indexes that represent cells containing know art images for things like hair, eyes, mouth etc.
It may take some experimentation to find the values for your character, but this is a simplified way to create repeatable characters.
Other ways to create consistent faces is to use one of the predefined Characters or hand code a face string.
skaraantorgothkralienarvonianzimniterran
self.face_desc = skaraan(0, 1,2,1,3)
Character Faces
The class Characters has a list of predefined face strings.
These are a good examples for creating a face string by hand.
The faces string syntax
Face string is a set of layers that reference a cell in a texture separated by a semi-colon. The first layer is the lowest layer.
the texture tag specified in allFaceFiles.txt a Tint to add to the layer. e.g. changing skin tone the cell's col the cell's row
optional to offset the layer in x optional to offset the layer in y
API: faces module
Characters
A set of predefined faces
arvonian(face_id, eye_id, mouth_id, crown_id, collar_id)
Create an arvonian face
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face_id
|
int
|
The index of the face 0 |
required |
eye_id
|
int
|
The index of the eyes 0-4 |
required |
mouth_id
|
int
|
The index of the mouth 0-4 |
required |
crown_id
|
int | None
|
The index of the crown 0-4 or None |
required |
collar_id
|
int | None
|
The index of the collar 0-4 or None |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
build_face(race, values, enables=None)
Build a face string from per-feature indices in FACE_FEATURES order.
values[i] is the chosen index for feature i; enables[i] False sets an
(optional) feature to None. Terran maps 1:1 to terran(); other races prepend
face_id 0 (the slot their builders expect). Returns '' for an unknown race.
clear_face(ship_id)
Removes a face string for a specified ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ship_id
|
Agent | int
|
The id of the ship/object |
required |
face_mod_reset()
Drop every mod registration. Called by reset_mission_state().
face_mod_size()
Reset-ledger probe: how much mod registration is currently held.
face_overlay(face_string, *overlays)
Stack overlay layers onto an existing face string.
This is the whole point of keeping implants as separate cells: any face can be assimilated at runtime, including one that was never drawn with implants. Layers composite lowest-first, so overlays go last.
face_overlay(random_face("terran"), "tng6 #fff 2 1", "tng6 #fff 5 3")
Empty/None overlays are skipped so a caller can pass an optional one straight in.
face_random_registered(race, role=None)
A random registered face for a race, or None if the race was never registered.
A role with no faces falls back to the race pool rather than returning nothing - asking for a Breen science officer should still get a Breen.
face_register_race(race, faces, roles=None, in_random=True)
Declare ready-made face strings for a race so random_face(race) can use them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
race
|
race name as scripts will ask for it, case-insensitive. |
required | |
faces
|
list of face strings - the pool used when no role is asked for. |
required | |
roles
|
optional {role: [face strings]} for role-filtered picks, e.g. random_face("klingon", "command"). |
None
|
|
in_random
|
whether a bare random_face()/random_face("random") may return this race. A mod that only wants its faces when asked for by name passes False. |
True
|
face_register_sheet(alias, cols=8, rows=8)
Declare a mod atlas alias and its cell grid.
alias is the short name in a face string ("tng1") and must match the name the
engine reads from data/graphics/allFaceFiles.txt - the library cannot write that
file, so registering here does NOT make the sheet loadable, it only teaches the
library and the browser compositor how to read cells out of it.
face_registered_sheets()
{alias: {"cols","rows"}} - what the mock compositor and AMD renderer need.
face_resolve(spec)
Resolve a declarative face spec to a face string. A KEYWORD (terran / male / female / fluid) -> a fresh random face of that kind; a literal face string -> itself unchanged; None/empty -> a random terran. Lets AMD/data author a face as a simple word instead of a raw face string. (Promoted from Open Universe's lifeform_face.)
face_sheet_grid(alias)
(cols, rows) for an alias. Stock geometry for the six built-ins: the Terran sheet is 15 wide, every other sheet is 8.
get_face(ship_id)
Returns a face string for a specified ID
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ship_id
|
Agent | int
|
The id of the ship/object |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
A Face string |
get_face_from_data(race)
Deprecated in v1.1.0.
Use random_race instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
race
|
_type_
|
description |
required |
Returns:
| Name | Type | Description |
|---|---|---|
_type_ |
description |
kralien(face_id, eye_id, mouth_id, scalp_id, extra_id)
Create an kralien face.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face_id
|
int
|
The index of the face 0 |
required |
eye_id
|
int
|
The index of the eyes 0-4 |
required |
mouth_id
|
int
|
The index of the mouth 0-4 |
required |
scalp_id
|
int | None
|
The index of the scalp 0-4 or None |
required |
extra_id
|
int | None
|
The index of the extra 0-4 or None |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
parse_face(face_string)
Recover (race, values, enables) from a face string — the inverse of build_face. Returns None if the string is not a recognized face. The result rebuilds to the same visual face via build_face (indices reproduce the same cells), so an editor can seed its controls from an existing face.
probably(chance)
Will compare a float with a random float between 0 and 1. If the provided number is larger than the random number, will return True. Args: chance (float): A float between 0 and 1.
random_arvonian()
Create a random arvonian face.
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_face(race=None, role=None)
Returns a random face for the specified race.
Mod races registered with face_register_race() are checked FIRST, so an add-on can supply "klingon" or "cardassian" without this function knowing they exist. That is what the TODO which used to sit here was asking for.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
race
|
str
|
The Race Terran, Torgoth etc, or a registered mod race. |
None
|
role
|
str
|
optional role filter for registered races ("command", "ops"...). Ignored by the six stock races, which have no role concept. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
The Face String |
random_kralien()
Create a random kralien face.
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_skaraan()
Create a random skaraan face.
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_terran(face=None, civilian=None)
Create a random terran face.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face
|
int | None
|
The index of the hair 0=male,1=female,2=fluid male, 3=fluid female or None= random |
None
|
civilian
|
boolean | None
|
The force this to be a civilian=True, For non-civilian=False or None= random |
None
|
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_terran_female(civilian=None)
Create a random terran female face.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
civilian
|
boolean
|
The force this to be a civilian=True, For non-civilian=False or None= random. Default is None. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_terran_fluid(civilian=None)
Create a random fluid terran face i.e. may have male or female features.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
civilian
|
boolean
|
The force this to be a civilian=True, For non-civilian=False or None= random. Default is None. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_terran_male(civilian=None)
Create a random terran male face.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
civilian
|
boolean
|
The force this to be a civilian=True, For non-civilian=False, or None= random. Default is None. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_torgoth()
Create a random torgoth face.
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
random_ximni()
Create a random ximni face.
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
set_face(ship_id, face)
Sets a face string for a specified ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ship_id
|
Agent | int
|
The id of the ship/object |
required |
face
|
str
|
A Face string |
required |
skaraan(face_id, eye_id, mouth_id, horn_id, hat_id)
Create a skaraan face
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face_id
|
int
|
The index of the face 0 |
required |
eye_id
|
int
|
The index of the eyes 0-4 |
required |
mouth_id
|
int
|
The index of the mouth 0-4 |
required |
horn_id
|
int | None
|
The index of the horn 0-4 or None |
required |
hat_id
|
int | None
|
The index of the hat 0-4 or None |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
terran(face_id, eye_id, mouth_id, hair_id, longhair_id, facial_id, extra_id, uniform_id, skintone, hairtone)
Create a terran face.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face_id
|
int | None
|
The index of the face 0=male, 1=female, 2=fluid_male, 3=fluid_female |
required |
eye_id
|
int | None
|
The index of the eyes 0-9 |
required |
mouth_id
|
int
|
The index of the mouth 0-9 |
required |
hair_id
|
int | None
|
The index of the hair 0-9 or None |
required |
longhair_id
|
int | None
|
The index of the hair 0-7 or None |
required |
facial_id
|
int | None
|
The index of the hair 0-11 or None |
required |
extra_id
|
int | None
|
The index of the extra 0-5 or None |
required |
uniform_id
|
int | None
|
The index of the uniform 0 or None. None = civilian |
required |
skintone
|
int | str | None
|
The index of the skintone 0-??, string = color string or None. |
required |
hairtone
|
int | str | None
|
The index of the skintone 0-??, string = color string or None. |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
torgoth(face_id, eye_id, mouth_id, hair_id, extra_id, hat_id)
Create a torgoth face.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face_id
|
int
|
The index of the face 0 |
required |
eye_id
|
int
|
The index of the eyes 0-4 |
required |
mouth_id
|
int
|
The index of the mouth 0-4 |
required |
hair_id
|
int | None
|
The index of the hair 0-4 or None |
required |
extra_id
|
int | None
|
The index of the extra 0-4 or None |
required |
hat_id
|
int | None
|
The index of the hat 0 or None |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Face string |
ximni(face_id, eye_id, mouth_id, horns_id, mask_id, collar_id)
Create an ximni face
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
face_id
|
int
|
The index of the face 0 |
required |
eye_id
|
int
|
The index of the eyes 0-4 |
required |
mouth_id
|
int
|
The index of the mouth 0-4 |
required |
horns_id
|
int | None
|
The index of the horns 0-4 or None |
required |
mask_id
|
int | None
|
The index of the mask 0-4 or None |
required |
collar_id
|
int | None
|
The index of the collar 0 or None |
required |
Returns:
| Type | Description |
|---|---|
str
|
A Face string |