world.list_characters

Overview

• Returns all characters in the simulation world with pagination. Supports filtering by group type and alive status.

Metadata

Field	Value
Display	List World Characters
Category	world
Access	Public
Scope	B2Authority
Tags	—
Aliases	—

Parameters

Name	Type	Required	Default	Description
group_type	string	no	—	Filter by group type: ResidenceFamily, CompanyRoleNpc, SiteRoleNpc, Crowd, EventCrowd, ServiceNpc, StaticNpc, ShopNpc
limit	int	no	—	Max characters to return (default: 50)
offset	int	no	—	Skip first N matched characters (default: 0)
alive_only	bool	no	—	Exclude dead characters (default: true)

Returns

Returns a JSON object with the following fields:

Field	Type	Required	Description
total	int	yes	Total matched characters
offset	int	yes	Pagination offset
limit	int	yes	Pagination limit
characters	array	yes	Characters in the simulation world
characters[].entity_id	entityId	yes	Character entity id
characters[].first_name	string	yes	First name
characters[].last_name	string	yes	Last name
characters[].household_id	entityId	no	Character's household id
characters[].gender	string	no	Gender enum name
characters[].age_group	string	no	Age group enum name
characters[].gender_text	string	no	Localized gender
characters[].age_group_text	string	no	Localized age group
characters[].current_site	string	no	Current site name
characters[].portrait_url	string	no	Cached portrait URL
characters[].is_married	bool	no	Whether married
characters[].spouse_id	entityId	no	Spouse entity id (if married)
characters[].has_career	bool	yes	Has any career
characters[].employable	bool	yes	Eligible for new employment
characters[].job_name	string	no	Localized job name
characters[].job_rank	int	no	Job rank
characters[].job_rank_name	string	no	Localized job rank name
characters[].relationship_label	string	no	Relationship label toward the possessed character
characters[].group_type	string	yes	Character group type enum name

Usage

await inzoi.cli.execute('world.list_characters', {
  group_type: '', // optional
  limit: 0, // optional
  offset: 0, // optional
  alive_only: false, // optional
});