Skip to content

Commit 43dd927

Browse files
HedgefogHedgefog
committed
add readme
1 parent 1227501 commit 43dd927

File tree

1 file changed

+392
-0
lines changed

1 file changed

+392
-0
lines changed

‎api/player-model/README.md‎

Lines changed: 392 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,392 @@
1+
2+
# Player Model API
3+
4+
## Working With Models
5+
6+
To change player model use `PlayerModel_Set` and `PlayerModel_Update` natives.
7+
`PlayerModel_Set` is using to set player model, calling `PlayerModel_Update` will force update model.
8+
```cpp
9+
PlayerModel_Set(pPlayer, "player/model/vip/vip.mdl"); // set current player model
10+
PlayerModel_Update(pPlayer); // force update player model
11+
```
12+
13+
14+
## Working with animations
15+
16+
The API supports loading custom animations, including additional weapon animations from separate files.
17+
18+
### Precaching animation
19+
20+
To precache the animation use `PlayerModel_PrecacheAnimation` native, it will precache animation from `animations` directory. This example will precache animation from `cstrike/animations/my-mod/player.mdl`:
21+
```cpp
22+
PlayerModel_PrecacheAnimation("my-mod/player.mdl");
23+
```
24+
25+
### Set custom weapon animation
26+
27+
Customize weapon animations by set `m_szAnimExtension` member. The following example sets the animation to `ref_aim_mysupergun`:
28+
```cpp
29+
static const szCustonWeaponExt[] = "mysupergun";
30+
31+
set_ent_data_string(pPlayer, "CBasePlayer", "m_szAnimExtention", szCustonWeaponExt);
32+
set_ent_data(pPlayer, "CBaseMonster", "m_Activity", ACT_IDLE);
33+
rg_set_animation(pPlayer, PLAYER_IDLE);
34+
```
35+
36+
37+
## Making animations file
38+
39+
### Creating Animation Files
40+
41+
#### Basic Animations
42+
Fist of all you have to provide basic player sequences like `walk`, `run`, `flitch`, etc.
43+
44+
<details>
45+
<summary>Example</summary>
46+
47+
```cpp
48+
$sequence "dummy" {
49+
"anims/dummy"
50+
fps 24
51+
loop
52+
}
53+
$sequence "idle1" {
54+
"anims/idle1"
55+
ACT_IDLE 1
56+
fps 15
57+
loop
58+
}
59+
$sequence "crouch_idle" {
60+
"anims/crouch_idle"
61+
ACT_CROUCHIDLE 1
62+
fps 10
63+
loop
64+
}
65+
$sequence "walk" {
66+
"anims/walk"
67+
ACT_WALK 1
68+
fps 30
69+
loop
70+
LX
71+
}
72+
$sequence "run" {
73+
"anims/run"
74+
ACT_RUN 1
75+
fps 60
76+
loop
77+
LX
78+
}
79+
$sequence "crouchrun" {
80+
"anims/crouchrun"
81+
ACT_CROUCH 1
82+
fps 30
83+
loop
84+
LX
85+
}
86+
$sequence "jump" {
87+
"anims/jump"
88+
ACT_HOP 1
89+
fps 36
90+
}
91+
$sequence "longjump" {
92+
"anims/longjump"
93+
ACT_LEAP 1
94+
fps 36
95+
}
96+
$sequence "swim" {
97+
"anims/swim"
98+
ACT_SWIM 1
99+
fps 30
100+
loop
101+
}
102+
$sequence "treadwater" { "anims/treadwater"
103+
ACT_HOVER 1
104+
fps 24
105+
loop
106+
}
107+
$sequence "gut_flinch" {
108+
"anims/gut_flinch_blend01"
109+
"anims/gut_flinch_blend02"
110+
"anims/gut_flinch_blend03"
111+
"anims/gut_flinch_blend04"
112+
"anims/gut_flinch_blend05"
113+
"anims/gut_flinch_blend06"
114+
"anims/gut_flinch_blend07"
115+
"anims/gut_flinch_blend08"
116+
"anims/gut_flinch_blend09"
117+
blend XR -90 90
118+
fps 30
119+
}
120+
$sequence "head_flinch" {
121+
"anims/head_flinch_blend01"
122+
"anims/head_flinch_blend02"
123+
"anims/head_flinch_blend03"
124+
"anims/head_flinch_blend04"
125+
"anims/head_flinch_blend05"
126+
"anims/head_flinch_blend06"
127+
"anims/head_flinch_blend07"
128+
"anims/head_flinch_blend08"
129+
"anims/head_flinch_blend09"
130+
blend XR -90 90
131+
fps 30
132+
}
133+
```
134+
</details>
135+
136+
137+
#### Fake reference
138+
Ensure your animation model includes at least one polygon. Here's an example SMD file for a fake reference:
139+
140+
<details>
141+
<summary>animreference.smd</summary>
142+
143+
```cpp
144+
version 1
145+
nodes
146+
0 "Bip01" -1
147+
1 "Bip01 Pelvis" 0
148+
2 "Bip01 Spine" 1
149+
3 "Bip01 Spine1" 2
150+
4 "Bip01 Spine2" 3
151+
5 "Bip01 Spine3" 4
152+
6 "Bip01 Neck" 5
153+
7 "Bip01 Head" 6
154+
8 "Bone01" 7
155+
9 "Bip01 L Clavicle" 6
156+
10 "Bip01 L UpperArm" 9
157+
11 "Bip01 L Forearm" 10
158+
12 "Bip01 L Hand" 11
159+
13 "Bip01 L Finger0" 12
160+
14 "Bip01 L Finger01" 13
161+
15 "Bip01 L Finger1" 12
162+
16 "Bip01 L Finger11" 15
163+
17 "-- L knuckle" 15
164+
18 "-- L Forearm twist" 11
165+
19 "-- L wrist" 11
166+
20 "-- L Elbow" 10
167+
21 "-- L bicep twist" 10
168+
22 "-- L shoulder outside" 9
169+
23 "-- L Shoulder inside" 9
170+
24 "Bip01 R Clavicle" 6
171+
25 "Bip01 R UpperArm" 24
172+
26 "Bip01 R Forearm" 25
173+
27 "Bip01 R Hand" 26
174+
28 "Bip01 R Finger0" 27
175+
29 "Bip01 R Finger01" 28
176+
30 "Bip01 R Finger1" 27
177+
31 "Bip01 R Finger11" 30
178+
32 "-- R knuckle" 30
179+
33 "-- R wrist" 26
180+
34 "-- R forearm twist" 26
181+
35 "-- R Elbow" 25
182+
36 "-- R bicep twist" 25
183+
37 "-- R Shoulder inside" 24
184+
38 "-- R shoulder outside" 24
185+
39 "-- Neck smooth" 5
186+
40 "-- R Butt" 1
187+
41 "-- L butt" 1
188+
42 "Bip01 L Thigh" 1
189+
43 "Bip01 L Calf" 42
190+
44 "Bip01 L Foot" 43
191+
45 "Bip01 L Toe0" 44
192+
46 "-- L ankle" 43
193+
47 "-- L Knee" 42
194+
48 "Bip01 R Thigh" 1
195+
49 "Bip01 R Calf" 48
196+
50 "Bip01 R Foot" 49
197+
51 "Bip01 R Toe0" 50
198+
52 "-- R Ankle" 49
199+
end
200+
skeleton
201+
time 0
202+
0 0.233849 -2.251689 38.192150 0.000000 0.000000 -1.570795
203+
1 -2.276935 0.000003 -1.238186 -1.570795 -1.570451 0.000000
204+
2 1.797145 0.711796 -0.000002 -0.000004 -0.000001 0.000739
205+
3 4.118605 -0.003279 0.000000 0.000000 0.000000 0.000035
206+
4 4.118601 -0.003280 0.000000 0.000000 0.000000 0.000049
207+
5 4.118600 -0.003280 0.000000 0.000000 0.000000 -0.000009
208+
6 4.118531 -0.003538 0.000000 0.000000 0.000000 -0.019437
209+
7 4.443601 0.000000 0.000000 0.000000 -0.000001 0.201740
210+
8 1.426626 0.072724 0.002913 2.958476 -1.570796 0.000000
211+
9 0.000004 0.003534 1.732721 -0.000040 -1.501696 -3.122911
212+
10 6.384776 0.000000 0.000001 0.025648 -0.046980 0.004099
213+
11 10.242682 0.000000 -0.000002 0.000000 0.000000 -0.008014
214+
12 11.375562 0.000000 0.000005 -1.580468 -0.132234 0.009455
215+
13 0.728679 0.023429 -1.008292 1.705251 0.347372 0.567022
216+
14 2.136497 0.000000 0.000001 0.000000 0.000000 0.287979
217+
15 3.115505 -0.886041 -0.021431 -0.000782 0.000152 0.191986
218+
16 2.011151 0.000000 0.000000 0.000000 0.000000 0.659566
219+
17 1.734173 0.000003 0.000000 0.000000 0.000000 0.330185
220+
18 6.000001 0.000000 0.000000 -1.578050 0.000000 0.000000
221+
19 11.375562 0.000000 0.000005 -1.575523 -0.074433 0.005312
222+
20 10.510129 0.000000 0.000000 0.000000 0.000000 -1.574800
223+
21 5.500000 0.000000 -0.000001 -0.011814 0.000000 0.000000
224+
22 6.551491 0.000000 -0.000001 0.019708 -0.055281 0.008457
225+
23 6.551491 0.000000 -0.000001 0.010051 -0.028020 0.004425
226+
24 0.000004 0.003543 -1.732721 -0.000040 1.501696 -3.122992
227+
25 6.384777 0.000000 -0.000001 -0.025648 0.046980 0.004099
228+
26 10.242681 0.000000 0.000002 0.000000 0.000000 -0.008014
229+
27 11.375562 0.000000 -0.000002 1.580468 0.132234 0.009455
230+
28 0.728679 0.023429 1.008292 -1.705251 -0.347372 0.567022
231+
29 2.136496 -0.000001 0.000000 0.000000 0.000000 0.287979
232+
30 3.115505 -0.886040 0.021431 0.000782 -0.000152 0.191986
233+
31 2.011151 0.000000 0.000000 0.000000 0.000000 0.659566
234+
32 1.734173 -0.000001 0.000000 0.000000 0.000000 0.330185
235+
33 11.389366 -0.000819 0.158785 1.575523 0.074433 0.005312
236+
34 6.000001 0.000000 0.000003 1.575523 0.000000 0.000000
237+
35 10.510130 0.000000 -0.000001 0.000000 0.000000 -1.574800
238+
36 5.499999 0.000000 0.000001 0.010051 0.000000 0.000000
239+
37 6.551491 0.000000 0.000001 -0.010051 0.028020 0.004424
240+
38 6.551491 0.000000 0.000001 -0.010051 0.028020 0.004424
241+
39 4.226144 -0.003201 0.000000 0.000000 0.000000 0.000000
242+
40 0.000005 -0.000005 -3.713579 -0.006814 3.056983 -0.063787
243+
41 -0.000005 0.000005 3.713579 0.005299 -3.071082 -0.053070
244+
42 -0.000005 0.000007 3.619081 0.011132 -3.002289 -0.086533
245+
43 16.573919 0.000000 0.000000 0.000000 0.000000 -0.162458
246+
44 15.128179 0.000000 0.000001 0.000920 -0.139743 0.076637
247+
45 5.758665 4.244730 0.000000 0.000000 0.000000 1.570796
248+
46 15.708952 0.000001 0.000000 0.001562 -0.077726 0.040998
249+
47 17.210194 0.000000 0.000001 0.000000 0.000000 -1.486823
250+
48 0.000005 -0.000003 -3.619081 -0.011130 3.002286 -0.086533
251+
49 16.573919 0.000000 0.000000 0.000000 0.000000 -0.162458
252+
50 15.128179 0.000000 0.000000 -0.000920 0.139743 0.076637
253+
51 5.758665 4.244731 0.000000 0.000000 0.000000 1.570796
254+
52 15.708952 0.000000 0.000000 -0.001364 0.104219 0.055002
255+
end
256+
triangles
257+
black.bmp
258+
0 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000
259+
0 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000
260+
0 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000
261+
end
262+
```
263+
</details>
264+
265+
Use the `$body` command in your QC file to add this reference:
266+
267+
```cpp
268+
$body "studio" "animreference"
269+
```
270+
271+
#### Protecting Bones
272+
273+
Use a compiler like `DoomMusic's StudioMDL` to protect bones. Add `$protection` for each animation bone before references and sequences in the `.qc`:
274+
275+
<details>
276+
<summary>Example</summary>
277+
278+
```cpp
279+
$protected "Bip01"
280+
$protected "Bip01 Pelvis"
281+
$protected "Bip01 Spine"
282+
$protected "Bip01 Spine1"
283+
$protected "Bip01 Spine2"
284+
$protected "Bip01 Spine3"
285+
$protected "Bip01 Neck"
286+
$protected "Bip01 Head"
287+
$protected "Bone01"
288+
$protected "Bip01 L Clavicle"
289+
$protected "Bip01 L UpperArm"
290+
$protected "Bip01 L Forearm"
291+
$protected "Bip01 L Hand"
292+
$protected "Bip01 L Finger0"
293+
$protected "Bip01 L Finger01"
294+
$protected "Bip01 L Finger1"
295+
$protected "Bip01 L Finger11"
296+
$protected "-- L knuckle"
297+
$protected "-- L Forearm twist"
298+
$protected "-- L wrist"
299+
$protected "-- L Elbow"
300+
$protected "-- L bicep twist"
301+
$protected "-- L shoulder outside"
302+
$protected "-- L Shoulder inside"
303+
$protected "Bip01 R Clavicle"
304+
$protected "Bip01 R UpperArm"
305+
$protected "Bip01 R Forearm"
306+
$protected "Bip01 R Hand"
307+
$protected "Bip01 R Finger0"
308+
$protected "Bip01 R Finger01"
309+
$protected "Bip01 R Finger1"
310+
$protected "Bip01 R Finger11"
311+
$protected "-- R knuckle"
312+
$protected "-- R wrist"
313+
$protected "-- R forearm twist"
314+
$protected "-- R Elbow"
315+
$protected "-- R bicep twist"
316+
$protected "-- R Shoulder inside"
317+
$protected "-- R shoulder outside"
318+
$protected "-- Neck smooth"
319+
$protected "-- R Butt"
320+
$protected "-- L butt"
321+
$protected "Bip01 L Thigh"
322+
$protected "Bip01 L Calf"
323+
$protected "Bip01 L Foot"
324+
$protected "Bip01 L Toe0"
325+
$protected "-- L ankle"
326+
$protected "-- L Knee"
327+
$protected "Bip01 R Thigh"
328+
$protected "Bip01 R Calf"
329+
$protected "Bip01 R Foot"
330+
$protected "Bip01 R Toe0"
331+
$protected "-- R Ankle"
332+
```
333+
</details>
334+
335+
#### Custom Animation Sequences
336+
337+
Add your custom weapon animations:
338+
339+
<details>
340+
<summary>Example</summary>
341+
342+
```cpp
343+
$sequence "crouch_aim_myweapon" {
344+
"crouch_aim_myweapon_blend1"
345+
"crouch_aim_myweapon_blend2"
346+
"crouch_aim_myweapon_blend3"
347+
"crouch_aim_myweapon_blend4"
348+
"crouch_aim_myweapon_blend5"
349+
"crouch_aim_myweapon_blend6"
350+
"crouch_aim_myweapon_blend7"
351+
"crouch_aim_myweapon_blend8"
352+
"crouch_aim_myweapon_blend9"
353+
blend XR -90 90 fps 30 loop
354+
}
355+
$sequence "crouch_shoot_myweapon" {
356+
"crouch_shoot_grenade_blend1"
357+
"crouch_shoot_grenade_blend2"
358+
"crouch_shoot_grenade_blend3"
359+
"crouch_shoot_grenade_blend4"
360+
"crouch_shoot_grenade_blend5"
361+
"crouch_shoot_grenade_blend6"
362+
"crouch_shoot_grenade_blend7"
363+
"crouch_shoot_grenade_blend8"
364+
"crouch_shoot_grenade_blend9"
365+
blend XR -90 90 fps 30
366+
}
367+
$sequence "ref_aim_myweapon" {
368+
"ref_aim_myweapon_blend1"
369+
"ref_aim_myweapon_blend2"
370+
"ref_aim_myweapon_blend3"
371+
"ref_aim_myweapon_blend4"
372+
"ref_aim_myweapon_blend5"
373+
"ref_aim_myweapon_blend6"
374+
"ref_aim_myweapon_blend7"
375+
"ref_aim_myweapon_blend8"
376+
"ref_aim_myweapon_blend9"
377+
blend XR -90 90 fps 30 loop
378+
}
379+
$sequence "ref_shoot_myweapon" {
380+
"ref_shoot_grenade_blend1"
381+
"ref_shoot_grenade_blend2"
382+
"ref_shoot_grenade_blend3"
383+
"ref_shoot_grenade_blend4"
384+
"ref_shoot_grenade_blend5"
385+
"ref_shoot_grenade_blend6"
386+
"ref_shoot_grenade_blend7"
387+
"ref_shoot_grenade_blend8"
388+
"ref_shoot_grenade_blend9"
389+
blend XR -90 90 fps 30
390+
}
391+
```
392+
</details>

0 commit comments

Comments
 (0)