You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+5Lines changed: 5 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -51,7 +51,12 @@ Roblox reflection types for working with Instances in external tooling.
51
51
52
52
Bundled reflection database using types from rbx_reflection. Intended for users migrating from rbx_reflection 4.x and users who need reflection information statically.
53
53
54
+
## [rbx_reflector](rbx_reflector)
55
+
56
+
Command line utility to generate a reflection database for rbx_dom_lua and rbx_reflection_database.
57
+
54
58
## [rbx_util](rbx_util)
59
+
55
60
Command line utility to convert and debug Roblox model files.
Copy file name to clipboardExpand all lines: docs/patching-database.md
+24-68Lines changed: 24 additions & 68 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# How to Fix a New Property Added by Roblox
2
-
When Roblox introduces new properties, usually tools like Rojo can use them without any additional changes. Sometimes, though, properties are added with different names, multiple serialized forms, or aren't listed at all in the reflection dump that Roblox gives us.
2
+
When Roblox introduces new properties, usually tools like Rojo can use them without any additional changes. Sometimes however, properties are added that have a different serialized name or that need to be modified with a special API in Lua.
3
3
4
-
This document describes some common scenarios, and what work needs to happen to fix them.
4
+
This document describes some common scenarios and the necessary steps to fix them.
5
5
6
6
## Roblox added a new property and it serializes with the expected name and type
7
7
When Roblox introduces a new property, try saving a place or model in the XML format (rbxlx or rbxmx) and look for the property.
@@ -30,33 +30,11 @@ This is not ideal, though. To let Rojo users write the nice, short property synt
30
30
Make sure you're running the latest version of Roblox Studio, then run the `./gen-reflection` script from the [rbx-dom repo][rbx-dom]. Patching Rojo's dependencies will let you test the change and make sure it works.
31
31
32
32
## Roblox added a new property and it serializes with a _weird_ name
33
-
Sometimes Roblox adds properties whose serialized names are different than their canonical names (the names exposed to users). To fix these issues, we need to introduce a _property patch_.
33
+
Sometimes a property is added with a serialized name different from its canonical name (the name exposed to users). To fix this issue, we need to introduce a _property patch_.
34
34
35
-
Property patches live in the [patches][patches] folder of the rbx-dom repository. There is roughly one YAML file per class that has changes applied to it. The `generate_reflection` tool reads these patches and uses them to generate a higher-quality reflection database for Rojo and other tools.
35
+
Property patches live in the [patches][patches] folder in the rbx-dom repository. There is roughly one YAML file per class that has changes applied to it. The `rbx_reflector` tool reads these patch files and uses them to generate an accurate reflection database for Rojo and other tools.
36
36
37
-
To fix this kind of issue, we need to introduce two different patches:
38
-
1. Add a new property descriptor for the funny name version of this property
39
-
2. Change the canonical property to indicate that it serializes with that funny name
40
-
41
-
One property that serializes with a different name is `Sound.MaxDistance`. It serializes with the name `xmlRead_MaxDistance_3`. Funky! Let's look at the two patches we need to write.
42
-
43
-
The first part of our patch file should introduce the serialized version of the property:
44
-
45
-
```yaml
46
-
Add:
47
-
Sound:
48
-
xmlRead_MaxDistance_3:
49
-
AliasFor: MaxDistance
50
-
DataType:
51
-
Value: Float32
52
-
Scriptability: None
53
-
```
54
-
55
-
The first two lines indicate that we're adding one or more new property descriptor for the class named `Sound`. We can have many properties here.
56
-
57
-
Next, we name the property that we're going to add. We say that it's an alias for `MaxDistance`, the canonical name for this property. It is a value type, not an enum, and the type is `Float32`. Because this property is only for serialization, it is not scriptable.
58
-
59
-
The second part of the patch we need is for adjusting the existing property, `MaxDistance`.
37
+
One property that serializes with a different name is `Sound.MaxDistance`. It serializes with the name `xmlRead_MaxDistance_3`. Funky! Let's look at the patch we need to write to fix it:
60
38
61
39
```yaml
62
40
Change:
@@ -65,70 +43,48 @@ Change:
65
43
Serialization:
66
44
Type: SerializesAs
67
45
As: xmlRead_MaxDistance_3
46
+
xmlRead_MaxDistance_3:
47
+
AliasFor: MaxDistance
68
48
```
69
49
70
-
Similar to before, the first two lines indicate that we're going to change some properties on the `Sound` class. We give the property name, `MaxDistance`, and then say that we're going to change its `Serialization`. We spell out that it will serialize as `xmlRead_MaxDistance_3`.
71
-
72
-
For this property, we're done!
50
+
The first two lines indicate that we're changing one or more properties for the class named `Sound`.
73
51
74
-
Here are a couple other common cases that can come up:
52
+
Next we change the `Serialization` of `MaxDistance` to serialize as `xmlRead_MaxDistance_3`.
75
53
76
-
### The serialized property name already exists
77
-
Sometimes, we don't need to add the serialized property name as it's already in the database from the reflection dump.
54
+
Finally, we say that `xmlRead_MaxDistance_3` is an alias for `MaxDistance`, the canonical name of the property.
78
55
79
-
One example of that is `Players.MaxPlayers`, which serializes as `MaxPlayersInternal`. For whatever reason, that property is reflected to users, and so it's already in the database.
56
+
For this property, we're done!
80
57
81
-
Instead of adding a new descriptor, we can update `MaxPlayersInternal` to point to its canonical form:
58
+
## Roblox added a new property, but modifying it from Lua requires a special API
59
+
Sometimes a property is added that cannot be assigned directly from Lua. For example, the `Model.Scale` property:
82
60
83
-
```yaml
84
-
Change:
85
-
Players:
86
-
MaxPlayers:
87
-
Serialization:
88
-
Type: SerializesAs
89
-
As: MaxPlayersInternal
90
-
MaxPlayersInternal:
91
-
AliasFor: MaxPlayers
61
+
```lua
62
+
-- This line of code throws an error: "Scale is not a valid member of Model"
63
+
model.Scale = 2
92
64
```
93
65
94
-
## Roblox added a new property, but modifying it from Lua requires a special API
95
-
Sometimes a property is added that cannot be assigned directly from Lua.
96
-
97
-
First up, modify the reflection database to either add or change the property's `Scriptability` to `Custom`:
66
+
To fix this, first patch the property's `Scriptablity` to `Custom`:
98
67
99
68
```yaml
100
-
# To add the property:
101
-
Add:
102
-
LocalizationTable:
103
-
# 'Contents' is the name of the field in the Roblox file formats, so it
104
-
# makes sense to use it as the canonical name of this property.
105
-
Contents:
106
-
Serialization:
107
-
Type: Serializes
108
-
DataType:
109
-
Value: String
110
-
Scriptability: Custom
111
-
112
69
# To change the property:
113
70
Change:
114
-
LocalizationTable:
115
-
Contents:
71
+
Model:
72
+
Scale:
116
73
Scriptability: Custom
117
74
```
118
75
119
-
Next, add an entry in [`rbx_dom_lua/src/customProperties.lua`][custom-properties] and implement the `read` and `write` methods. They return whether they succeeded as their first value.
76
+
Next, add an entry in [custom-properties] and implement the `read` and `write` methods. They return whether they succeeded as their first value.
0 commit comments