Skip to content

Commit

Permalink
Updated entity properties page
Browse files Browse the repository at this point in the history
  • Loading branch information
@QuazChick
QuazChick committed Jan 10, 2025
1 parent bbdbad6 commit 2b1a262
Showing 1 changed file with 98 additions and 70 deletions.
168 changes: 98 additions & 70 deletions docs/entities/entity-properties.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,129 +15,157 @@ mentions:

Entity properties (also known as actor properties) allow data to be stored on entities without needing the use of components or attributes (such as `minecraft:variant`) in the server-side of the entity, similar to block states.

## Entity Properties Definition
## Defining Properties

### Defining Properties on Entities
Entity properties are defined in the BP entity's `description` object:

Entity Properties Definition:

<CodeHeader></CodeHeader>
<CodeHeader>BP/entities/properties_example.json</CodeHeader>

```json
{
"format_version": "1.21.50",
"minecraft:entity": {
"description": {
"identifier": "wiki:properties_example",
"properties": {
"wiki:number_range_example": {
"values": {
"min": 0,
"max": 100
}
"wiki:bool_property_example": {
"type": "bool",
"default": false
},
"wiki:number_enum_example": {
"values": [1, 2]
"wiki:enum_property_example": {
"type": "enum",
"values": ["first", "second", "third"],
"default": "first"
},
"wiki:string_enum_example": {
"values": ["first", "second", "third"]
"wiki:float_property_example": {
"type": "float",
"range": [0, 3.14],
"default": 2.5
},
"wiki:boolean_enum_example": {
"values": [true, false]
"wiki:int_property_example": {
"type": "int",
"range": [0, 4],
"default": 4
}
}
}
},
"components": { ... },
"events": { ... }
}
}
```

### Entity Properties Object Fields

#### `values`
### Default Value

:::warning
`values` property is required, and omitting this field may cause errors and failure to register the property.
:::
Default values, determined by the `default` parameter, can be defined either as specific values or as Molang expressions.

`values` field can be evaluated as an array of enum values, or a range of minimum and maximum values (Note that integer, float, and boolean enum values currently supports only two values):
A string value will be treated as a Molang expression unless it is an enum value.
Molang expressions are evaluated when the entity is first spawned.

<CodeHeader></CodeHeader>
<CodeHeader>minecraft:entity > description > properties</CodeHeader>

```json
"wiki:range_example": {
"values": {
"min": 0,
"max": 5
}
"example:enum_property_example": {
"type": "enum",
"values": ["first", "second", "third"],
"default": "math.random_integer(0, 1) ? 'first' : 'second'"
}
```

**OR**
### Client Sync

To access a property from the resource pack (client-side), the `client_sync` parameter must be `true`.
By default, this value is `false`.

<CodeHeader></CodeHeader>
<CodeHeader>minecraft:entity > description > properties</CodeHeader>

```json
"wiki:enum_example":{
"values":[
1,
2
]
"wiki:is_sad": {
"type": "bool",
"default": false,
"client_sync": true
}
```

#### `default`

You can set the default value of the entity property (by default, the first value of the enum array index) through the `default` field inside the defined property object:
Let's set a variable to the value of this property for use in an animation!

<CodeHeader></CodeHeader>
<CodeHeader>minecraft:client_entity > description</CodeHeader>

```json
"wiki:default_value_example":{
"values":[
true,
false
],
"default":false
"scripts": {
"pre_animation": [
"v.is_sad = q.property('wiki:is_sad');"
]
}
```

As you can observe, the default property is set to `false` instead of `true` when the entity is spawned in the world.
## Getting Property Values

### Molang Query Function

#### `client_sync`
Property values are returned by the `property` query function.

To sync through the Resource Pack (client-side), `client_sync` field can be used to allow the Client Entity access the Entity Properties. By default, the value is set to `false`.
<CodeHeader>Molang Expression</CodeHeader>

```c
!q.property('wiki:bool_property_example')
```

<CodeHeader></CodeHeader>
### Entity Filter Test

<CodeHeader>Entity Filter</CodeHeader>

```json
"wiki:client_sync_example": {
"values": {
"min": 0,
"max": 20
},
"client_sync": true
{
"test": "bool_property",
"domain": "wiki:bool_property_example",
"operator": "==",
"value": true
}
```

### Manipulating and Accessing Entity Properties
### Command Selector Parmeter

You can access entity properties through Molang Entity Queries: - `q.property` - `q.has_property`
<CodeHeader>Command</CodeHeader>

:::warning
These Molang Entity Queries are a part of Experimental features
:::
```c
testfor @e[has_property={wiki:enum_property_example="second"}]
```
### Script API
The [`Entity.getProperty()`](https://learn.microsoft.comminecraft/creator/scriptapi/minecraft/server/entity#getproperty) method allows you to get the current value of different properties.
<CodeHeader>Script</CodeHeader>
```js
customEntity.getProperty("wiki:int_property_example") === 2;
```

## Setting Property Values

### Entity Event Response

With entity events, you may set the entity property to a value with the `set_property` event response:

<CodeHeader></CodeHeader>
<CodeHeader>minecraft:entity > events</CodeHeader>

```json
"events":{
"wiki:set_entity_property":{
"set_property":{
"wiki:number_enum_example":2,
"wiki:string_enum_example":"'second'",
"wiki:boolean_enum_example":"!q.property('wiki:boolean_enum_example')"
}
"wiki:set_entity_property": {
"set_property": {
"wiki:integer_property_example": 2,
"wiki:enum_property_example": "second",
"wiki:boolean_property_example": "!q.property('wiki:boolean_enum_example')"
}
}
```

### Script API

The [`Entity.setProperty()`](https://learn.microsoft.comminecraft/creator/scriptapi/minecraft/server/entity#setproperty) method allows you to set the value of a properties.

<CodeHeader>Script</CodeHeader>

```js
customEntity.setProperty("wiki:int_property_example", 2);
```

0 comments on commit 2b1a262

Please sign in to comment.