Model Settings

scriptfiles/3dandreas/models.json describes models as A3D_CreateObject makes them. A model listed there moves with the shape the file gives it and starts with its mass, friction, bounce, damping, rolling friction, buoyancy and sync error. A model left out keeps the collision of the game, and its mass, friction and bounce are estimated from the model itself.

The file gives a shape to models the game leaves without one, such as balls and weapons, gives real values where the estimate falls short, and lets one file hold what each script would otherwise set on every object it creates.

{
    "1946": {
        "name": "baskt_ball_hi",
        "shape": "sphere",
        "radius": 0.208,
        "offset": [0.003, 0.008, 0.003],
        "mass": 0.62,
        "friction": 1.8,
        "bounce": 0.8,
        "linear_damping": 0.1,
        "angular_damping": 0.05,
        "rolling_friction": 0.15,
        "buoyancy": 10.0,
        "sync_error": 0.03
    },
    "346": {
        "name": "colt45",
        "shape": "box",
        "size": [0.248, 0.053, 0.183],
        "offset": [0.118, 0.03, 0.036],
        "mass": 1.1
    }
}

With that file, a basketball needs one line:

new Physic:ball = A3D_CreateObject(1946, x, y, z);

Which natives read it

Only A3D_CreateObject takes the values of the file, and its mass only when the script passes 0.0, the default. A mass given by the script wins. A3D_OverlapModel and A3D_IsModelColliding use the shape of the file too, since it is the shape the model moves with.

A3D_CreateSphere and A3D_CreateBox give their own shape and keep the defaults, whatever their model. Natives such as A3D_SetBounce still change one object after it is created.

Settings

Every setting is optional. The keys of the file are model ids, and custom models of a server, with negative ids, may be listed too.

Setting	Value	Default
name	Text for whoever reads the file. The component ignores it.
shape	"model", "sphere", "box" or "cylinder"	"model", the convex hull of the collision
radius	Radius of a sphere or a cylinder, in metres	Half the average size of the model
height	Height of a cylinder, in metres	The size of the model along axis
axis	"x", "y" or "z", the axis of the model a cylinder lies along	"z"
size	[x, y, z], the size of a box in metres	The size of the model
offset	[x, y, z], the centre of the shape from the origin of the model	The middle of the model
mass	Mass in kilograms, above 0	The estimate
friction	As A3D_SetFriction	That of the material, or 0.5
bounce	As A3D_SetBounce	That of the material, or 0.3
linear_damping	As the linear value of A3D_SetDamping	0.1
angular_damping	As the angular value of A3D_SetDamping	0.3
rolling_friction	As A3D_SetRollingFriction	0.0
buoyancy	As A3D_SetBuoyancy. 0 sinks.	0.0
drag	The drag of A3D_SetBuoyancy	1.0
sync_error	As A3D_SetSyncError, above 0	3dandreas.sync_error

The sizes the file leaves out come from the bounds of the model in the map database, so "shape": "sphere" alone makes a sphere as wide as the model. A model that is not in the database, such as a weapon, needs every size of its shape. "model" needs a model with collision in the database.

Models the file leaves out

A model the file does not list, and each mass, friction and bounce an entry leaves out, comes from the model itself. The component works it out the first time A3D_CreateObject makes the model and keeps it.

• The material is the one of the surfaces covering most of the area of the collision. Most models carry DEFAULT, which says nothing, and count as unknown.
• The mass is the volume of the shape the model moves with times the density of its material. A model built only of spheres and boxes counts the volume of those parts when it is smaller than its convex hull, so a lamp post is not weighed with the air between its arms.
• The friction and the bounce are those of the material. An unknown material keeps 0.5 and 0.3.

Material	Surfaces	Density	Friction	Bounce
Unknown	DEFAULT, the ground and the rest	80	0.5	0.3
Metal	THICK_METAL_PLATE, LAMP_POST, METAL_BARREL, CONTAINER, CAR and the other metals	100	1.01	0.2
Wood	WOOD_CRATES, WOOD_SOLID, DOOR, the wooden fences and furniture	50	1.25	0.3
Glass	GLASS, GLASS_WINDOWS_LARGE, GLASS_WINDOWS_SMALL, UNBREAKABLE_GLASS	300	0.61	0.2
Plastic	PLASTIC, PLASTICBARRIER, PLASTIC_CONE, PLASTIC_DUMPSTER	70	0.8	0.35
Rubber	RUBBER, WHEELBASE	150	1.8	0.5
Cardboard	CARDBOARDBOX	15	1.25	0.05
Cloth	TRANSPARENT_CLOTH, CARPET, STAIRSCARPET, BIN_BAG	30	1.8	0.03
Stone	ROCK_DRY, FLOORCONCRETE, TARMAC, PAVEMENT, GRAVEL and the other stones	1500	1.25	0.1
Plant	HEDGE, VEGETATION, FLOWERBED, CORNFIELD, HAY_BALE	50	1.8	0.05

Densities are in kilograms per cubic metre of the shape, so they count the air inside a hollow object and sit far below the density of the solid material: a steel drum is a thin shell. They were fitted on the 203 models of the file of a release, and the estimate lands within twice the chosen mass for half of them and within three times for two thirds. Some of what it gives: a cardboard box 6 kg, a barrel 34 kg, a bin 11 to 17 kg, a dumpster 100 to 370 kg, a lamp post 190 kg. Objects that are mostly air, such as bags, hats and flowers, come out heavier than they are, and small solid ones, such as a fire hydrant, lighter. The file lists the ones that matter. Masses stop at 50 grams and at 50 tonnes, where buildings and land end.

Mistakes

A mistake in a model leaves that model out and writes a warning that names it, and the other models still load:

[Warning] [3DAndreas] scriptfiles/3dandreas/models.json: model 1946: there is no setting "bounse", so the model is left out

A file that is not valid JSON is not read at all, and the warning gives the line. The component writes how many models it read when the server starts:

3DAndreas 0.6.3: 203 models described by scriptfiles/3dandreas/models.json, read in 1.2 ms

The file is read once, into a table found by model id, so a longer file only adds to that line: making an object costs the same with ten models listed or ten thousand.

The path is 3dandreas.models in Configuration. A missing file is no mistake: every model then keeps the collision of the game.

The file of a release

The file of a release describes 203 models: the balls of the game, common props such as crates, barrels and cones, and the models a roleplay server usually turns into items, from weapons and tools to food, bottles, televisions and furniture.

• The size and centre of every sphere, box and cylinder were measured on the model players see, in the DFF files of the game, so the shape covers the model. The muzzle flash of each gun is left out.
• A model keeps the collision of the game where it fits. A pickup whose collision is one sphere, such as cash or body armour, becomes a box, so it does not roll away like a ball. Cans, bottles, barrels and extinguishers are cylinders, so they roll on their side.
• Masses are those of the real objects: 0.62 kg for a basketball, as FIBA requires, 1.1 kg for a pistol, 4.3 kg for an assault rifle, 0.37 kg for a can.
• The bounce of a basketball is 0.8, which drops it from 1.8 metres back to the height FIBA requires. Other bounces follow the material.
• The map carries a friction of 0.2, and a contact takes the square root of the product of both frictions. So each friction in the file is chosen for the real coefficient of the material on concrete: 1.8 for rubber slides like 0.6, and 1.0 for metal like 0.45.
• Balls, wood, cardboard and cloth float. A buoyancy of 10 keeps a ball a tenth under the water. Metal, glass and electronics sink.

The values of object.dat, which A3D_GetModelPhysics reads, were not used as they are: the game gives a beer bottle 50 kilograms and a beach ball 1000.