Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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_zr68s.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68s.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68s.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68s.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_jinrai_zr68s.vvd
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68s.dx80.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68s.dx90.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68s.mdl
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68s.sw.vtx
Binary file not shown.
Binary file added neo/models/weapons/v_nsf_zr68s.vvd
Binary file not shown.
62 changes: 51 additions & 11 deletions neo/modelsrc/weapons/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Weapon model sources

The Tachi and ZR68C viewmodels are the first weapons maintained under these conventions, followed by the MilSO.
The Tachi and ZR68C viewmodels are the first weapons maintained under these conventions, followed by the ZR68-S
and MilSO.
Expect the folder layout, scripts and steps here to change as more weapons are added.

## Change an animation (quick recipe)
Expand All @@ -11,7 +12,8 @@ For example, a new pose in a slot of the Tachi. Run the commands from this folde
Viewport, press N and pick the **Viewmodel** tab.
2. Pick the scene `jinrai_tachi` (top right) and the slot in Dope Sheet > Action Editor > Slot. The panel shows the
slot's kind: **authored** (a new slot: edit freely) or **shipped** (keep the original; see Exporting animations).
Click **Frame range to slot**. **Team** shows the other team's arms; the same keys move both.
Click **Frame range to slot**. **Team** shows the other team's arms; the same keys move both. In a family base
scene (`jinrai_zr68c`), **Variant** shows a variant's gun (silencer, scope) on the same keys.
3. Pose and key the bones. Click **Check slot**: it selects any bone a range-of-motion limit stops.
4. If such a pose is meant: click **Free selected bones**, key the pose, then click **Widen to this slot** and type
the reason. This adds a line to `rom_widen.json` and refreshes the limits of every rig (about 8 s).
Expand All @@ -23,22 +25,25 @@ For example, a new pose in a slot of the Tachi. Run the commands from this folde
Layout:

- `viewmodels.blend`: the Blender file for every viewmodel. It holds one **scene** per gun, called a project:
`jinrai_tachi`, `jinrai_zr68c` and `jinrai_milso`. Each scene has one rig and one action, and both teams' arms (see One scene per
gun).
`jinrai_tachi`, `jinrai_zr68c`, `jinrai_zr68s` and `jinrai_milso`. Each scene has one rig and one action, and both teams' arms
(see One scene per gun).
- `PROJECT/` (such as `jinrai_tachi/`): the project's `.qc`, `reference.smd`, `anims/*.smd` (written by the
export) and `composites.txt` (if used). The scripts take project names.
- `nsf_GUN/` (such as `nsf_zr68c/`): the NSF model's `.qc`, `reference.smd` and its shipped clips in `anims/`. It has
no scene and is never exported: it compiles from these SMDs and from the Jinrai glued clips.
- `jinrai_GUN/glued.qci` (guns with glued clips, now the ZR68C): the `$sequence` lines of the glued clips, read from
`jinrai_GUN/anims/`. Both team `.qc` files include it, so the NSF model compiles the Jinrai glued clips.
- `jinrai_GUN/glued.qci` (guns with glued clips, now the ZR68C): the `$sequence` lines of the glued
clips, read from `jinrai_GUN/anims/`. Both team `.qc` files include it, so the NSF model compiles the Jinrai glued
clips. The variants of a gun family include their base gun's file instead (see Gun families).
- `GUN/viewmodel.qci` (such as `tachi/viewmodel.qci`): the QC lines both team models of a gun share. Each team's `.qc`
sets only `$modelname` and includes this file. The MilSO keeps a whole `.qc` per team, as its team models differ
in more than their bones.
sets only `$modelname` and includes this file. The ZR68-S follows the ZR68C layout
(`zr68s/viewmodel.qci`).
- `arms/textures/` (Jinrai and NSF arms, shared by every weapon) and `GUN/textures/`: preview images the `.blend` loads.
- `rom_limits.py`, `rom_spec.json` and `rom_widen.json`: the range-of-motion limits on the rigs (see
Range-of-motion limits).
- `merge_teams.py`: the one-time merge of the two team scenes of each gun into one (already applied; kept for the
record and for a gun added later with two scenes).
- `variant_preview.py`: the one-time build of the variant guns in the family base scenes (already applied; see Gun
families, Variant toggle). It stops at a scene that already has gun collections.
- `glue.py`: the glued clips, the phases file and the post-export preview; the export uses it (see Reload resume
animations).
- `viewmodels_post_export.blend`: export output, a preview of the glued clips (see Previewing the glued clips).
Expand Down Expand Up @@ -73,6 +78,35 @@ teams' arm meshes are skinned to that rig, so a key moves both. Each team's mesh

The Tachi has no glued clips.

### Gun families

A variant compiles the glued clips of its base gun, so the base gun authors the new slots for the whole family:

| base gun | variants that compile its glued clips |
| :-- | :-- |
| ZR68C (`jinrai_zr68c`) | ZR68-S |

- Both team `.qc` files of a variant end with `$include "../jinrai_BASE/glued.qci"`. The variant has no
`composites.txt`, no `glued.qci` and no authored or glued SMDs.
- The variant's scene keeps its shipped slots and the step markers on its `reload`. Its export writes the shipped
slots and fills its own phases file from the base's `composites.txt`, with the base's markers overridden by the
variant's own. It fails if a variant marker moves a join (the glued clips are built at the base's frames). A new
slot left in a variant scene prints `FAMILY WARN` and is not exported: author it on the base gun.
- Exporting a base gun also exports its variants (their phases files). Compile the base and its variants.
- A bone the base's SMDs lack (a silencer, a scope) stays at the variant's own rest pose in the glued clips; the
shared bones, the `Muzzle` and `Eject` points included, follow the base. The variants' shipped clips have the
base's motion and attachment points on the shared bones.
- **Variant toggle:** the base scene shows each variant's gun on the base rig and action, to check a new slot on
every gun that plays it. The team collections hold the arms only; the guns are in collections `BASE_gun` and
`VARIANT_gun` (`zr68c_gun`, `zr68s_gun`), one visible at a time. Pick the gun in the **Variant** dropdown of the
Viewmodel panel, or click the eye of its collection in the Outliner.
- The variant gun has no bones of its own in that scene: `variant_preview.py` moved the weights of its own parts to
the nearest bone of the base rig, at the variant's rest pose (the ZR68-S `Silencer` to `zr68c`, `x_silenced` to
`Dummy02`). The glued clips carry no track for those bones, so the game also holds the parts at their rest pose
under that bone. The preview matches the variant's own scene within 0.025 units in every shared shipped slot (the
ZR68-S ships its own `melee01`). Nothing exported depends on these collections: their objects have Source Tools
export off.

| term | meaning |
| :-- | :-- |
| sequence | one animation the game plays, such as `reload`. One SMD file in `anims/`, one `$sequence` line in the `.qc`. |
Expand Down Expand Up @@ -242,6 +276,10 @@ A reload with a round chambered keeps that round and leaves out the bolt pull. T

The `"resume"` key on a row of the phases file names the clip to draw after that step.

The ZR68-S compiles the ZR68C's glued clips (Gun families). Its step markers sit at `1_unload` f20, `2_load` f42
(the ZR68C's at f21, f40 on the same motion; no join moves). It plays the ZR68C's sound pieces
(`weapon_zr68.reload_*`).

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

Expand Down Expand Up @@ -303,8 +341,9 @@ To add a resume clip after another step:

`viewmodels_post_export.blend` shows each glued clip exactly as the game plays it, easing included. It is an export
output: every export rebuilds it from `viewmodels.blend` and the glued SMDs, for every project with a
`composites.txt` (the Jinrai projects; the NSF models play the same clips). Each scene there has both teams' arms:
**Team** or the collection eye shows the other. Never edit it; edit `viewmodels.blend` and export. Commit it together with the SMDs whenever a
`composites.txt` (the Jinrai projects; the NSF models and the family variants play the same clips). Each scene there has both teams' arms:
**Team** or the collection eye shows the other. A family base scene also has the variants' guns: **Variant** or the
eye of a `GUN_gun` collection shows one. Never edit it; edit `viewmodels.blend` and export. Commit it together with the SMDs whenever a
glued clip changes.

1. Open `viewmodels_post_export.blend` in Blender.
Expand Down Expand Up @@ -374,7 +413,8 @@ Files in neoAssets (this repo):
the shipped clips only).
- `neo/modelsrc/weapons/GUN/viewmodel.qci`: the QC lines the two teams share.
- `neo/modelsrc/weapons/jinrai_GUN/composites.txt` and `glued.qci` (if the gun has glued clips): Jinrai project only.
End both team `.qc` files with `$include "../jinrai_GUN/glued.qci"`.
End both team `.qc` files with `$include "../jinrai_GUN/glued.qci"`. A variant of a gun family (same motion on
the shared bones in its shipped `reload`) includes the base gun's file instead and gets no new slots.
- `neo/scripts/weapon_GUN_reload_phases.txt`: the phases file. Copy the ZR68C one and edit the sequences and steps.
- `neo/sound/weapons/GUN/GUN_<key>.wav`: one wav per sound entry.
- `neo/modelsrc/weapons/rom_spec.json`: once the shipped slots are in, run `rom_limits.py -- spec` and `apply`
Expand Down
37 changes: 35 additions & 2 deletions neo/modelsrc/weapons/export_viewmodels.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
Requires Blender 5.2.3 or newer and Blender Source Tools 3.4.3 or newer.
This helper reads viewmodels.blend, and writes SMD exports.
glue.py beside this script, when present, adds glued clips and reload phase times (its docstring has the rules).
A family variant (a gun whose .qc includes another gun's ../jinrai_BASE/glued.qci, such as the ZR68-S with the ZR68C)
compiles the base's glued clips and authors no slot of its own: its export writes its shipped slots only (FAMILY WARN
for a slot it still has, which is not exported). Exporting a base also exports its variants.
Before any SMD is written, the range-of-motion check of rom_limits.py runs over every slot of the listed projects
and fails the export when a ROM:* constraint clamps a keyed pose; the export itself runs with ROM:* muted, so the
SMDs are the keyed poses (an active Local-Space constraint changes them by float round-off even when nothing clamps).
Expand Down Expand Up @@ -76,6 +79,16 @@ def shipped_slots(folder):
return set(SHIPPED_SMD.findall(qc_text(folder)))


GLUED_INCLUDE = re.compile(r'^\$include\s+"\.\./(jinrai_[^/"]+)/glued\.qci"', re.M)


def family_base(folder):
"""The family base project of a variant (the gun whose glued.qci its .qc includes), or None. A variant compiles the
base's glued clips and authors no slot of its own."""
bases = [name for name in GLUED_INCLUDE.findall(qc_text(folder)) if name != folder.name]
return folder.parent / bases[0] if bases else None


def read_markers(scene):
return {marker.name: marker.frame for marker in scene.timeline_markers}

Expand Down Expand Up @@ -308,13 +321,22 @@ def open_scenes(path, keep=None):
return bpy.context.scene


def export_project(folder, scene, allow_shipped=False):
def export_project(folder, scene, allow_shipped=False, markers=None):
if scene.render.fps != FPS or scene.render.fps_base != 1:
raise RuntimeError('Scene %s must play at %d fps' % (scene.name, FPS))
reference = folder / 'reference.smd'
reference_bytes = reference.read_bytes()
armature = project_rig(scene)
rom_limits.set_mute(scene, True) # this copy of the file is never saved
base = family_base(folder)
if base:
action, keep = armature.animation_data.action, shipped_slots(folder)
for slot in [slot for slot in action.slots if slot.name_display not in keep]:
print('FAMILY WARN %s has its own slot %s, which is not exported: %s authors the family\'s new slots. '
'Delete the slot' % (scene.name, slot.name_display, base.name))
action.slots.remove(slot) # this copy of the file is never saved
if armature.animation_data.action_slot is None:
armature.animation_data.action_slot = action.slots[0]
expected = [folder / 'anims' / (slot.name_display + '.smd')
for slot in armature.animation_data.action.slots]
previous = {path: path.stat().st_mtime_ns if path.exists() else None
Expand All @@ -334,6 +356,11 @@ def export_project(folder, scene, allow_shipped=False):
changed = guard_shipped(folder, before, allow_shipped)
print('EXPORTED', scene.name, len(expected), 'animation SMD files; reference retained')
copy_shipped(folder, changed)
if base:
print('FAMILY', scene.name, 'compiles the glued clips of', base.name)
if glue:
glue.after_variant(folder, base, read_markers(scene), markers[base.name])
return
if glue:
glue.after_export(folder, scene)
shipped = shipped_slots(folder)
Expand All @@ -356,12 +383,18 @@ def export_project(folder, scene, allow_shipped=False):
unknown = [project for project in projects if project not in found or not (root / project).is_dir()]
if unknown:
raise RuntimeError('No scene and folder named ' + ', '.join(unknown))
variants = [path.name for path in sorted(root.glob('jinrai_*')) if path.name not in projects and
next(path.glob('*.qc'), None) and family_base(path) and family_base(path).name in projects]
if variants:
print('FAMILY also exporting', ', '.join(variants), '(their phases files follow the base markers)')
projects += variants
for project in projects:
project_rig(found[project])
check_images()
check_limits([found[project] for project in projects])
markers = {scene.name: read_markers(scene) for scene in found}
for project in projects:
export_project(root / project, open_scenes(root / SOURCE, keep=project), allow_shipped)
export_project(root / project, open_scenes(root / SOURCE, keep=project), allow_shipped, markers)
if glue:
glue.build_post_export(root)
except RuntimeError as problem:
Expand Down
Loading