Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
0b58c4d
Join exported animations listed in composites.txt
sunzenshen Nov 8, 2026
e406a7c
Add the Jinrai ZR68C Blender project
sunzenshen Nov 8, 2026
989c25f
Add the NSF ZR68C Blender project
sunzenshen Nov 8, 2026
10d2171
Add the compiled Jinrai ZR68C viewmodel
sunzenshen Nov 8, 2026
a374513
Add the compiled NSF ZR68C viewmodel
sunzenshen Nov 8, 2026
4d2c3f2
Add the ZR68 reload seat, slap and bolt sounds
sunzenshen Nov 8, 2026
474ec1c
Explain how to add a ZR68C reload resume clip
sunzenshen Nov 8, 2026
0cf5007
Mark the ZR68C reload resume frame in Blender
sunzenshen Nov 8, 2026
5b72b31
Mark the ZR68C reload join and timing frames
sunzenshen Nov 8, 2026
9010360
Derive resume joins and reload times from markers
sunzenshen Nov 8, 2026
1e7f4f3
Ship the ZR68C reload phases as a timed script file
sunzenshen Nov 8, 2026
74ae64f
Share the arm preview images across viewmodels
sunzenshen Nov 8, 2026
c14c6d6
Name the ZR68C reload steps by number
sunzenshen Nov 8, 2026
45ee39c
Time a step's ammo from its step marker
sunzenshen Nov 8, 2026
183d629
End the ZR68C resume when the gun is ready
sunzenshen Nov 8, 2026
b4114e2
End the ZR68C resume when the bolt is home
sunzenshen Nov 8, 2026
04acb02
Play the ZR68C resume to the end, fire at 4_ready
sunzenshen Nov 8, 2026
f3c45bf
Fire no earlier than the last reload sound ends
sunzenshen Nov 8, 2026
879e741
Cut the ZR68C reload sounds to play on time
sunzenshen Nov 8, 2026
358bda0
Fire when the ZR68C hands are back at rest
sunzenshen Nov 8, 2026
ee0a7ec
Fire at the end of the ZR68C resume clip
sunzenshen Nov 8, 2026
43c4ff2
Name the ZR68C resume in the phases file
sunzenshen Nov 8, 2026
0c2939a
Add the M41 resume after the unload (sketch)
sunzenshen Nov 8, 2026
b83593f
Describe the M41 sketch in the weapons README
sunzenshen Nov 8, 2026
a0d3482
Add the MilSO resume after the unload (sketch)
sunzenshen Nov 8, 2026
2e51a72
Stub the open reload TODOs as comments
sunzenshen Nov 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added neo/models/weapons/v_jinrai_milso.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_milso.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_milso.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_milso.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_milso.vvd
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_mosok41.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_mosok41.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_mosok41.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_mosok41.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_mosok41.vvd
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68c.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68c.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68c.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68c.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68c.vvd
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_milso.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_milso.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_milso.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_milso.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_milso.vvd
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_mosok41.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_mosok41.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_mosok41.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_mosok41.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_mosok41.vvd
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68c.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68c.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68c.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68c.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68c.vvd
Binary file not shown.
113 changes: 111 additions & 2 deletions neo/modelsrc/weapons/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# Weapon model sources

The Tachi viewmodels are the first weapons maintained under these conventions.
The Tachi viewmodels are the first weapons maintained under these conventions, followed by the ZR68C (`jinrai_zr68c/`, `nsf_zr68c/`).
SKETCH (sunzenshen): `jinrai_mosok41/` and `nsf_mosok41/` add the M41 resume after `1_unload`; their transition slot,
sounds and arm previews are placeholders (see "M41 sketch" below).
Preview images the `.blend` files load live in `arms/textures/` for the Jinrai and NSF arms (shared by every weapon)
and in a weapon folder for the weapon, such as `tachi/textures/` or `zr68c/textures/`.
Expect the folder layout, scripts and steps here to change as more weapons are added.

Each model has a source folder here, such as `jinrai_tachi/`, containing one `.blend` file and one `.qc` file.
Expand All @@ -15,6 +19,62 @@ To export from Blender to SMD, for example for both Tachi projects, run:
blender --background --python-exit-code 1 --python export_viewmodels.py -- jinrai_tachi nsf_tachi
```

A sequence made of parts of other animations is written after the export, when the source folder has a `composites.txt`.
Each line names the output animation and its parts in order; a part is a slot, `slot:first-last` for a frame range
(inclusive, an empty `last` runs to the end), or `slot@step-last` to start after the step's join marker (see below).
For example, `resume_after_1_unload_empty resume_after_1_unload_transition reload@1_unload-` writes
`anims/resume_after_1_unload_empty.smd`: all of the `resume_after_1_unload_transition` slot, then `reload` from the frame after
the marker `reload:1_unload.join` to its end. Across each join, the last 3 frames of the previous part are eased onto the pose the
next part continues from (`blend=N` at the end of the line sets the count). The export prints the gap and fails if it
exceeds 0.5 units or 2 degrees.


## Reload resume animations (ZR68C)

When the player switches weapons after the old magazine is out, the reload continues when the gun is drawn again.
The game plays `resume_after_1_unload_empty` for this: a draw that brings the fresh magazine up, then the rest of `reload`.
The `"resume"` key on the `1_unload` row of `reload` in the phases file names it.

The animator makes the motion look right and places markers; the export does the frame and time arithmetic.
The `README_ANIMATOR` text block in each `.blend` repeats these rules.

### Naming

| name | meaning |
| :-- | :-- |
| `1_unload`, `2_load`, `3_cycle` | reload steps: old magazine out, new magazine in, round chambered. The number belongs to the step type; a gun without a step skips its number. |
| `reload:1_unload` | step marker on `reload`: the frame the step is done and its ammo counts, and the default join of `resume_after_1_unload` |
| `reload:1_unload.join` | optional: moves that join (the ZR68C joins at f30, after the ammo point at f21) |
| `slot:step.sound`, `.sound2` | sound markers: when each of the step's sounds first hits |
| `resume_after_1_unload_transition` | authored slot: the draw up to the join pose, named after the last finished step |
| `resume_after_1_unload_empty` | generated: the slot glued to the rest of `reload`. Source style: `_empty` (as in `reloadempty`, `idle01empty`) is the clip for an empty gun, the bare name `resume_after_1_unload` the one with a round left. |
| `weapon_zr68.reload_2_load`, `reload_2_load_2` | sound entries of a step (`_2` for its second sound, the tap after loading), wav files named the same |

A resume after step N plays only the sounds of the steps after N: `resume_after_2_load` would never play the tap.
The export fails on a `resume_after_N` row for step N or earlier.

### Markers and times

- The `resume_after_1_unload_transition` slot holds only the new motion. It ends on the `reload` pose at the join marker.
A small difference is eased out at export.
- The export shifts the timing markers into every composite and rewrites every time in
`neo/scripts/weapon_<gun>_reload_phases.txt`, the `ReloadPhases` block that neo's weapon script includes with `#base`.
A row without a marker fails the export, and so does an ammo time at or after the sequence's last frame.
- A row's `"resume"` key names the sequence the draw plays when a switch interrupts that sequence after the step.
The export keeps the key and fails unless it names a `resume_after_STEP...` sequence of the row's own step.
- A sequence ends where the gun can fire: the export fails if one of its sounds plays past its last frame. A clip
that keeps moving after both hands are at rest is trimmed in its source slot; there is no marker for it.

To add a resume clip after another step:

1. Place the step marker `reload:STEP` (and `reload:STEP.join` if the join is elsewhere), and add a slot
`resume_after_STEP_transition` that ends on that pose.
2. Add a line to `composites.txt`, such as `resume_after_STEP_empty resume_after_STEP_transition reload@STEP-`, and a
`$sequence` line for it to the `.qc`.
3. In `neo/scripts/weapon_<gun>_reload_phases.txt`, add `"resume" "resume_after_STEP_empty"` to the `STEP` row of
`reload`, and a table for the resume with the rows of the later steps (any time). Then export and compile.
A new weapon also needs `#base "weapon_<gun>_reload_phases.txt"` and an empty `"ReloadPhases" {}` in its neo script.


## Compiling models

Expand All @@ -24,4 +84,53 @@ Set `--compiler` to Source SDK Base 2013 Multiplayer's `studiomdl.exe`, and `--g
python compile_viewmodels.py jinrai_tachi nsf_tachi --compiler "C:/Program Files (x86)/Steam/steamapps/common/Source SDK Base 2013 Multiplayer/bin/studiomdl.exe" --game "C:/path/to/neo/game/neo"
```

To save the compiled models in neoAssets, copy the generated files (`v_*_tachi.*` for the Tachi) from the neo game directory's `models/weapons/` folder to `neo/models/weapons/`.
To save the compiled models in neoAssets, copy the generated files (`v_*_tachi.*` for the Tachi, `v_*_zr68c.*` for the ZR68C) from the neo game directory's `models/weapons/` folder to `neo/models/weapons/`.


## M41 sketch (`jinrai_mosok41/`, `nsf_mosok41/`)

Sketch of adding a second gun the same way as the ZR68C, resume after `1_unload` only. Source folders are named after the
model (`mosok41`), sound entries and wavs after the weapon (`weapon_m41.reload_2_load`, `m41_reload_2_load.wav`), so the
phases file is `weapon_mosok41_reload_phases.txt` and neo's `weapon_m41.txt` includes it.

- Built from the research M41 sources (decompiled shipped viewmodel): `reference.smd`, the 14 shipped sequences, and the
QC with the generated `resume_after_1_unload_empty` added. The `.blend` files have no preview images yet.
- `resume_after_1_unload_transition` is a placeholder: the research glued clip (draw into `reload`), of which
`composites.txt` takes frames 0-40; frame 40 equals `reload` f33, the join (`reload:1_unload.join` f33).
- `reload` has 3 sounds in step `2_load` (seat rattle, tap, slap) and 1 in `3_cycle` (bolt click). The `2_load` row uses
all three sound slots. The wavs are the research cuts, not re-cut by the ZR68C method.
- Compiled `v_jinrai_mosok41.*`, `v_nsf_mosok41.*` are new in neoAssets (only the `mosok41l` models were here); their
vertex data has the shipped size and 5 materials, not compared byte for byte.


## MilSO sketch (`jinrai_milso/`, `nsf_milso/`)

Second gun after the M41 sketch, resume after `1_unload`; it has two reload sequences, so two families:

| family | reload | resume slot (authored) | resume clip (glued) |
| :-- | :-- | :-- | :-- |
| tactical, slide forward | `reload` | `resume_after_1_unload_transition` | `resume_after_1_unload` |
| dry, slide back, `3_cycle` = slide release | `reloadempty` | `resume_after_1_unload_empty_transition` | `resume_after_1_unload_empty` |

- Each `1_unload` row of the phases file names its own resume, so the code needs nothing MilSO-specific.
- Markers exist per sequence: `reload:1_unload`, `reloadempty:1_unload` (+ `.join`), `:2_load` (+ `.sound`), `reloadempty:3_cycle`.
- The slide release has no sound; `3_cycle` carries only an ammo time.
- Both transition slots are the research glued clips (placeholders); composites take frames 0-34 (f34 equals `reload` / `reloadempty` f24).
- Compiled `v_*_milso.*` are new in neoAssets.

## Sketch status

Parked until the ZR68C MVP gets reviewer feedback.

### Per-gun TODO (M41)

`composites.txt` takes no comments. Open: real base projects (animator pass, arm textures), name for a one-reload gun
(`_empty` or bare), fire point (clip end vs `ReloadReadyBeforeEnd` 0.393 s), ship the compiled base models, six projects
(M41, M41S, M41L, two teams) or shared clips, resume after `2_load`, run tests (flag on/off, bots, third person).

### Per-gun TODO (MilSO)

`composites.txt` takes no comments. Open: row 5 (resume after the load on the dry pistol, needs a resume that keeps the
clip), chambered round kept on a tactical resume, `holsterempty` vs `holster` choice during a dry resume, slot and glue names
for a gun with two families, fire point (`ReloadReadyBeforeEnd` 0.467 s vs 1.167 s load), ship `v_*_milso`, replace the
placeholder seat wav.
165 changes: 165 additions & 0 deletions neo/modelsrc/weapons/export_viewmodels.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,174 @@
Each SOURCE is a folder beside this script that contains one .blend file.
Requires Blender 5.2.2 and Blender Source Tools 3.4.3 or newer.
This helper reads .blend sources, and writes SMD exports.
An optional composites.txt in a source folder joins exported animations into one more SMD per line:
OUTPUT PART [PART ...] [blend=N], where PART is SLOT, SLOT:FIRST-LAST (inclusive frames; an empty LAST means
the end) or SLOT@STEP-LAST (from the frame after timeline marker SLOT:STEP.join, else SLOT:STEP). Across a join,
the last N frames (default 3) of the previous part are eased onto the pose the next part continues from.
Timeline markers time the rows of neo/scripts/weapon_GUN_reload_phases.txt (GUN: the folder name after its team
prefix): the step marker SLOT:STEP gives the step's "ammo" time, SLOT:STEP.KEY (KEY sound, sound2, ...) the others.
The export rewrites each time there, shifted into composites.
A sequence resume_after_STEP... may list only the steps after STEP: a resume never replays an earlier step's sound.
A row's "resume" key names the sequence that resumes the reload interrupted after that step: resume_after_STEP...
A sequence's ammo times come before its last frame, and its sounds finish playing by then: the gun can fire there.
"""
from pathlib import Path
import math
import re
import sys
import wave

import bpy
from mathutils import Euler, Quaternion

FPS = 30
SOUND_LEAD = 0.02 # neo starts a reload sound piece this long before its time (RELOAD_SOUND_LEAD)
EXACT = 1e-4 # below the SMD print precision: the poses match, nothing is eased
SEAM_LIMIT_UNITS, SEAM_LIMIT_DEGREES = 0.5, 2.0 # eased over 3 frames: less than the reload moves per frame


def read_frames(path):
"""The header up to 'skeleton', and the frames as lists of bone lines."""
lines = path.read_text(encoding='ascii').splitlines()
start = lines.index('skeleton')
frames = []
for line in lines[start + 1:]:
if line.startswith('time '):
frames.append([])
elif line != 'end':
frames[-1].append(line)
return lines[:start + 1], frames


def pose(line):
bone, *values = line.split()
values = list(map(float, values))
return bone, values[:3], Euler(values[3:])


def ease_seam(output, joined, target, count):
"""Spread the gap to the target pose over the last frames; fail on a gap no short ease can hide."""
distance = angle = 0.0
count = min(count, len(joined))
for index, goal in enumerate(target):
bone, position, rotation = pose(joined[-1][index])
_, goal_position, goal_rotation = pose(goal)
move = [g - p for g, p in zip(goal_position, position)]
turn = goal_rotation.to_quaternion() @ rotation.to_quaternion().inverted()
distance, angle = max(distance, math.dist(position, goal_position)), max(angle, math.degrees(turn.angle))
if max(map(abs, move)) < EXACT and turn.angle < EXACT:
continue
for step in range(1, count + 1):
frame, weight = joined[step - count - 1], step / count
_, at, spin = pose(frame[index])
spin = (Quaternion().slerp(turn, weight) @ spin.to_quaternion()).to_euler('XYZ', spin)
frame[index] = bone + ' ' + ' '.join('%.6f' % v for v in [a + weight * m for a, m in zip(at, move)] + list(spin))
text = '%s seam gap %.4f u, %.3f deg (blend %d frames)' % (output, distance, angle, count)
if distance > SEAM_LIMIT_UNITS or angle > SEAM_LIMIT_DEGREES:
raise RuntimeError('SEAM TOO FAR ' + text + ': pose the transition\'s last frame on the marked frame')
print('SEAM', text)


def write_composites(folder, markers):
composites = folder / 'composites.txt'
times = {}
for name, frame in markers.items():
slot, _, key = name.partition(':')
if key:
times.setdefault(slot, {})[key] = frame
if not composites.is_file():
return times
for line in composites.read_text(encoding='ascii').splitlines():
if not line.strip():
continue
output, *parts = line.split()
count = int(parts.pop()[6:]) if parts[-1].startswith('blend=') else 3
header, joined = None, []
for part in parts:
slot, mark, span = re.match(r'(\w+)([:@]?)(.*)', part).groups()
if mark == '@':
step, _, last = span.partition('-')
join = markers.get(slot + ':' + step + '.join', markers.get(slot + ':' + step))
if join is None:
raise RuntimeError('No timeline marker %s:%s for %s' % (slot, step, part))
span = '%d-%s' % (join + 1, last)
part_header, frames = read_frames(folder / 'anims' / (slot + '.smd'))
if header is not None and part_header != header:
raise RuntimeError('Composite parts have different nodes: ' + part)
header = part_header
first, _, last = span.partition('-')
first, last = int(first or 0), int(last) if last else len(frames) - 1
if joined and first > 0 and count > 0:
ease_seam(output, joined, frames[first - 1], count)
for key, frame in times.get(slot, {}).items():
if first <= frame <= last:
times.setdefault(output, {})[key] = len(joined) + frame - first
joined += frames[first:last + 1]
body = [text for time, frame in enumerate(joined) for text in ['time %d' % time] + frame]
(folder / 'anims' / (output + '.smd')).write_text(
'\n'.join(header + body + ['end']) + '\n', encoding='ascii')
print('COMPOSED', output, len(joined), 'frames')
return times


def sound_end(path, name, at):
"""When the sound entry name (weapon_GUN.KEY, wav sound/weapons/GUN/GUN_KEY.wav) started for time at stops playing."""
gun, _, key = name.partition('_')[2].partition('.')
with wave.open(str(path.parents[1] / 'sound' / 'weapons' / gun / ('%s_%s.wav' % (gun, key)))) as clip:
return at - SOUND_LEAD + clip.getnframes() / clip.getframerate()


def check_ready(folder, path, text):
"""Fail when a sound of a sequence plays past the sequence's last frame, where the gun can fire."""
for sequence, body in re.findall(r'"(\w+)"\s*\{((?:[^{}]|\{[^{}]*\})*)\}', text):
ready = (len(read_frames(folder / 'anims' / (sequence + '.smd'))[1]) - 1) / FPS
for at in re.findall(r'"ammo" "([^"]*)"', body):
if float(at) >= ready - 1e-6:
raise RuntimeError('%s ends at %.3f s, not after an ammo time %s s' % (sequence, ready, at))
for key, at in re.findall(r'"(sound\d*)" "([^"]*)"', body):
name = re.search(r'"%s_name" "([^"]*)"' % key, body.split('"%s" "%s"' % (key, at), 1)[1])[1]
end = sound_end(path, name, float(at))
if ready < end - 1e-6:
raise RuntimeError('%s ends at %.3f s, before %s ends at %.3f s' % (sequence, ready, name, end))
print('READY %s %.3f s >= %s end %.3f s (%s - %.2f + wav)' % (sequence, ready, name, end, at, SOUND_LEAD))


def step_order(step):
"""The order of a reload step, from its name (1_unload -> 1)."""
return int(step.partition('_')[0])


WRITTEN = {} # phases file -> text from the first team project of this run


def fill_phases(folder, times):
"""Set every ammo/sound time in the weapon's ReloadPhases file from the markers; both teams must agree."""
path = folder.parents[2] / 'scripts' / ('weapon_%s_reload_phases.txt' % folder.name.partition('_')[2])
if not path.is_file():
return
sequence, lines = None, path.read_text(encoding='ascii').splitlines()
for number, line in enumerate(lines):
if re.fullmatch(r'\s*"\w+"\s*', line):
sequence = line.strip().strip('"')
step = re.match(r'\s*"(\w+)"\s*\{', line)
if step and sequence.startswith('resume_after_') and step_order(step[1]) <= step_order(sequence[13:]):
raise RuntimeError('%s lists step %s: a resume plays only later steps' % (sequence, step[1]))
resume = re.search(r'"resume" "(\w+)"', line) if step else None
if resume and not (resume[1].startswith('resume_after_') and step_order(resume[1][13:]) == step_order(step[1])
and (folder / 'anims' / (resume[1] + '.smd')).is_file()):
raise RuntimeError('%s row %s: %s is no resume_after_%s... sequence' % (sequence, step[1], resume[1], step[1]))
for key in re.findall(r'"(ammo|sound\d*)" "[^"]*"', line) if step else []:
marker = step[1] if key == 'ammo' else step[1] + '.' + key
frame = times.get(sequence, {}).get(marker)
if frame is None:
raise RuntimeError('No timeline marker %s:%s for %s' % (sequence, marker, path.name))
lines[number] = line = re.sub(r'("%s" )"[^"]*"' % key, r'\1"%.3f"' % (frame / FPS), line)
text = '\n'.join(lines) + '\n'
check_ready(folder, path, text)
if WRITTEN.setdefault(path, text) != text:
raise RuntimeError('The team projects give different times for ' + path.name)
path.write_text(text, encoding='ascii')
print('PHASES', path.name, '\n' + text)


def export_project(project):
Expand Down Expand Up @@ -36,6 +199,8 @@ def export_project(project):
if reference.read_bytes() != reference_bytes:
raise RuntimeError('The preview mesh must not overwrite reference.smd')
print('EXPORTED', project.name, len(expected), 'animation SMD files; reference retained')
markers = {marker.name: marker.frame for marker in bpy.context.scene.timeline_markers}
fill_phases(folder, write_composites(folder, markers))


if __name__ == '__main__':
Expand Down
Loading