ara3d 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/README.md +38 -8
  2. package/dist/cli.js +5 -5
  3. package/dist/embed.js +16579 -0
  4. package/dist/index.js +1877 -0
  5. package/dist/types/packages/cli/src/embed.d.ts +43 -0
  6. package/dist/types/packages/cli/src/index.d.ts +109 -0
  7. package/dist/types/packages/cli/src/library/colors.d.ts +9 -0
  8. package/dist/types/packages/cli/src/library/generate.d.ts +40 -0
  9. package/dist/types/packages/cli/src/library/sequence.d.ts +14 -0
  10. package/dist/types/packages/cli/src/library/worker.d.ts +22 -0
  11. package/dist/types/src/app/character-assist.d.ts +73 -0
  12. package/dist/types/src/app/share.d.ts +19 -0
  13. package/dist/types/src/core/anim/boarding.d.ts +4 -0
  14. package/dist/types/src/core/anim/clips/actions.d.ts +9 -0
  15. package/dist/types/src/core/anim/clips/aerial.d.ts +7 -0
  16. package/dist/types/src/core/anim/clips/basic.d.ts +4 -0
  17. package/dist/types/src/core/anim/clips/climbing.d.ts +37 -0
  18. package/dist/types/src/core/anim/clips/combat.d.ts +6 -0
  19. package/dist/types/src/core/anim/clips/cover.d.ts +19 -0
  20. package/dist/types/src/core/anim/clips/dodge.d.ts +8 -0
  21. package/dist/types/src/core/anim/clips/emotes.d.ts +21 -0
  22. package/dist/types/src/core/anim/clips/everyday.d.ts +15 -0
  23. package/dist/types/src/core/anim/clips/faces.d.ts +11 -0
  24. package/dist/types/src/core/anim/clips/gait.d.ts +17 -0
  25. package/dist/types/src/core/anim/clips/gunshot.d.ts +8 -0
  26. package/dist/types/src/core/anim/clips/helpers.d.ts +26 -0
  27. package/dist/types/src/core/anim/clips/index.d.ts +8 -0
  28. package/dist/types/src/core/anim/clips/interaction.d.ts +18 -0
  29. package/dist/types/src/core/anim/clips/lying.d.ts +8 -0
  30. package/dist/types/src/core/anim/clips/melee.d.ts +3 -0
  31. package/dist/types/src/core/anim/clips/mocap-data.d.ts +6 -0
  32. package/dist/types/src/core/anim/clips/reactions.d.ts +34 -0
  33. package/dist/types/src/core/anim/clips/recorded.d.ts +12 -0
  34. package/dist/types/src/core/anim/clips/runner.d.ts +10 -0
  35. package/dist/types/src/core/anim/clips/shooter.d.ts +15 -0
  36. package/dist/types/src/core/anim/clips/speech.d.ts +10 -0
  37. package/dist/types/src/core/anim/clips/swimming.d.ts +17 -0
  38. package/dist/types/src/core/anim/clips/types.d.ts +152 -0
  39. package/dist/types/src/core/anim/clips/vehicles.d.ts +28 -0
  40. package/dist/types/src/core/anim/evaluate.d.ts +188 -0
  41. package/dist/types/src/core/anim/mocap.d.ts +120 -0
  42. package/dist/types/src/core/anim/quat.d.ts +14 -0
  43. package/dist/types/src/core/anim/riding-weapons.d.ts +13 -0
  44. package/dist/types/src/core/anim/stage.d.ts +5 -0
  45. package/dist/types/src/core/assets.d.ts +114 -0
  46. package/dist/types/src/core/face.d.ts +56 -0
  47. package/dist/types/src/core/garments/bags.d.ts +2 -0
  48. package/dist/types/src/core/garments/beach.d.ts +9 -0
  49. package/dist/types/src/core/garments/body.d.ts +70 -0
  50. package/dist/types/src/core/garments/catalog.d.ts +8 -0
  51. package/dist/types/src/core/garments/drape.d.ts +86 -0
  52. package/dist/types/src/core/garments/dress-shoes.d.ts +7 -0
  53. package/dist/types/src/core/garments/earpiece.d.ts +2 -0
  54. package/dist/types/src/core/garments/gowns.d.ts +2 -0
  55. package/dist/types/src/core/garments/gulf.d.ts +2 -0
  56. package/dist/types/src/core/garments/heels.d.ts +8 -0
  57. package/dist/types/src/core/garments/index.d.ts +36 -0
  58. package/dist/types/src/core/garments/kit.d.ts +173 -0
  59. package/dist/types/src/core/garments/last.d.ts +78 -0
  60. package/dist/types/src/core/garments/layering.d.ts +4 -0
  61. package/dist/types/src/core/garments/necklaces.d.ts +2 -0
  62. package/dist/types/src/core/garments/outfit-cut.d.ts +30 -0
  63. package/dist/types/src/core/garments/prison.d.ts +2 -0
  64. package/dist/types/src/core/garments/project.d.ts +61 -0
  65. package/dist/types/src/core/garments/ring.d.ts +100 -0
  66. package/dist/types/src/core/garments/sets.d.ts +41 -0
  67. package/dist/types/src/core/garments/shell.d.ts +37 -0
  68. package/dist/types/src/core/garments/sheriff.d.ts +2 -0
  69. package/dist/types/src/core/garments/shirts.d.ts +31 -0
  70. package/dist/types/src/core/garments/sneakers.d.ts +7 -0
  71. package/dist/types/src/core/garments/street.d.ts +2 -0
  72. package/dist/types/src/core/garments/suit.d.ts +2 -0
  73. package/dist/types/src/core/garments/swimwear.d.ts +2 -0
  74. package/dist/types/src/core/garments/textures.d.ts +53 -0
  75. package/dist/types/src/core/garments/wrist.d.ts +2 -0
  76. package/dist/types/src/core/garments/yoruba.d.ts +2 -0
  77. package/dist/types/src/core/geometry.d.ts +31 -0
  78. package/dist/types/src/core/human.d.ts +42 -0
  79. package/dist/types/src/core/looks/hair.d.ts +64 -0
  80. package/dist/types/src/core/looks/index.d.ts +38 -0
  81. package/dist/types/src/core/looks/jewelry.d.ts +20 -0
  82. package/dist/types/src/core/looks/mouth.d.ts +12 -0
  83. package/dist/types/src/core/looks/overlay.d.ts +42 -0
  84. package/dist/types/src/core/looks/tattoos.d.ts +11 -0
  85. package/dist/types/src/core/looks/textures.d.ts +8 -0
  86. package/dist/types/src/core/math.d.ts +29 -0
  87. package/dist/types/src/core/mesh.d.ts +75 -0
  88. package/dist/types/src/core/morph.d.ts +11 -0
  89. package/dist/types/src/core/pack.d.ts +7 -0
  90. package/dist/types/src/core/params.d.ts +103 -0
  91. package/dist/types/src/core/props/bicycle.d.ts +26 -0
  92. package/dist/types/src/core/props/carry.d.ts +67 -0
  93. package/dist/types/src/core/props/helicopter-layout.d.ts +11 -0
  94. package/dist/types/src/core/props/horse-gait.d.ts +11 -0
  95. package/dist/types/src/core/props/parachute.d.ts +14 -0
  96. package/dist/types/src/core/props/stage-props.d.ts +23 -0
  97. package/dist/types/src/core/props/vehicle-actions.d.ts +23 -0
  98. package/dist/types/src/core/props/vehicle-bodies.d.ts +5 -0
  99. package/dist/types/src/core/props/vehicle-car.d.ts +2 -0
  100. package/dist/types/src/core/props/vehicle-doors.d.ts +2 -0
  101. package/dist/types/src/core/props/vehicle-helicopter.d.ts +2 -0
  102. package/dist/types/src/core/props/vehicle-horse.d.ts +2 -0
  103. package/dist/types/src/core/props/vehicle-kit.d.ts +61 -0
  104. package/dist/types/src/core/props/vehicle-land.d.ts +3 -0
  105. package/dist/types/src/core/props/vehicle-merge.d.ts +3 -0
  106. package/dist/types/src/core/props/vehicle-motion.d.ts +104 -0
  107. package/dist/types/src/core/props/vehicle-special.d.ts +3 -0
  108. package/dist/types/src/core/props/vehicle-stunt.d.ts +16 -0
  109. package/dist/types/src/core/props/vehicle-water.d.ts +2 -0
  110. package/dist/types/src/core/props/vehicle.d.ts +49 -0
  111. package/dist/types/src/core/props/vehicles.d.ts +60 -0
  112. package/dist/types/src/core/props/weapons.d.ts +21 -0
  113. package/dist/types/src/core/rig/poses.d.ts +7 -0
  114. package/dist/types/src/core/rig/rig.d.ts +75 -0
  115. package/dist/types/src/core/rig/skeletons.d.ts +33 -0
  116. package/dist/types/src/core/rig/socket.d.ts +21 -0
  117. package/dist/types/src/core/skin-rough.d.ts +11 -0
  118. package/dist/types/src/export/fbx.d.ts +10 -0
  119. package/dist/types/src/export/glb.d.ts +9 -0
  120. package/dist/types/src/export/index.d.ts +22 -0
  121. package/dist/types/src/export/obj.d.ts +6 -0
  122. package/dist/types/src/export/plan.d.ts +63 -0
  123. package/package.json +13 -4
@@ -0,0 +1,3 @@
1
+ import { VehicleKit } from './vehicle-kit';
2
+ export declare function buildCar(k: VehicleKit): void;
3
+ export declare function buildMotorcycle(k: VehicleKit): void;
@@ -0,0 +1,3 @@
1
+ /** Batch static pieces per rigid component and material, keeping moving joints independent. */
2
+ import * as T from 'three';
3
+ export declare function mergeVehicleParts(root: T.Group): void;
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Clip-authored vehicle manoeuvres: runway, flight, bail-out and gunner actions. Renderer-free, shared by
3
+ * the builder preview, exports and Studio. The builder and exports play the motion baked into the clip;
4
+ * Studio flies the aircraft along the film's own route and height instead.
5
+ */
6
+ import { type Q } from '../anim/quat';
7
+ import type { Vec3 } from '../math';
8
+ export type ManoeuvreKind = 'taxi' | 'takeoff' | 'land' | 'bailout' | 'gun' | 'crash';
9
+ /** Road vehicles a driver can dive out of as they crash. */
10
+ export declare const CRASH_VEHICLES: readonly [readonly ['car', 'drive_car'], readonly ['sports_car', 'drive_sports_car'], readonly ['suv', 'drive_suv'], readonly ['pickup', 'drive_pickup'], readonly ['motorcycle', 'ride_motorcycle'], readonly ['bicycle', 'ride_bicycle']];
11
+ export declare const VEHICLE_MANOEUVRES: Readonly<Record<string, {
12
+ ride: string;
13
+ kind: ManoeuvreKind;
14
+ }>>;
15
+ export declare const manoeuvre: (clip: string) => ManoeuvreKind;
16
+ /** Default speeds in metres per second. */
17
+ export declare const JET_SPEED = 18, TAXI_SPEED = 8;
18
+ /** Builder/export heights; Studio uses the film's flight height. */
19
+ export declare const DEMO_ALTITUDE = 2.5, BAILOUT_ALTITUDE = 4.5;
20
+ /**
21
+ * Seconds of full-speed travel covered after `local` seconds of a beat. Take-off accelerates from a
22
+ * standstill to cruise over its ground roll; landing holds approach speed, then brakes to a stop.
23
+ */
24
+ export declare function travelTime(clip: string, local: number, duration: number): number;
25
+ /** Take-off climbs after its ground roll; landing descends to touchdown at 60%, then rolls out. */
26
+ export declare function jetHeight(clip: string, u: number, cruise: number): number;
27
+ export interface FlightState {
28
+ pitch: number;
29
+ roll: number;
30
+ bob: number;
31
+ retract: number;
32
+ throttle: number;
33
+ }
34
+ /**
35
+ * How a flown jet sits: pitch follows the flight path (radians) plus a little angle of attack, wings bank a
36
+ * beat behind fly_jet's six-second stick cycle (`phase` seconds), and the gear folds once clear of the ground.
37
+ */
38
+ export declare function jetFlightState(clip: string, u: number, phase: number, time: number, height: number, path: number, moving: boolean): FlightState;
39
+ export interface VehicleMotion {
40
+ rotation: Q;
41
+ translation: Vec3;
42
+ retract: number;
43
+ throttle: number;
44
+ distance: number;
45
+ }
46
+ /** Pitch and bank about the main-gear contact (`pivotZ`), then lift and bob. */
47
+ export declare function attitudeMotion(s: FlightState, height: number, pivotZ: number, distance?: number): VehicleMotion;
48
+ /**
49
+ * Builder/export motion of the rider and aircraft together for jet clips, played in place: the wheels turn
50
+ * with the distance a film would cover, the jet lifts to a demonstration height and pitches with its climb.
51
+ * Bail-outs hold the aircraft at a safe height while the occupant leaves it.
52
+ */
53
+ export declare function clipVehicleMotion(clip: string, time: number, duration: number, pivotZ: number): VehicleMotion | undefined;
54
+ /**
55
+ * How far the aircraft has pulled ahead of a bailing occupant (metres along the heading). The jet keeps flying
56
+ * once the pilot is out; the helicopter holds its hover.
57
+ */
58
+ export declare function bailoutDrift(clip: string, time: number): number;
59
+ /**
60
+ * Bail-out paths (seconds; metres scaled to the rider): out through the open (right, -X) side, up and clear of the
61
+ * airframe, then turning belly-down into free fall. The last values are where free fall continues.
62
+ */
63
+ export declare const BAILOUT_PATHS: Readonly<Record<string, {
64
+ T: number[];
65
+ x: number[];
66
+ lift: number[];
67
+ pitch: number[];
68
+ pose: [number, number];
69
+ }>>;
70
+ /**
71
+ * Crash escape (seconds; metres scaled to the rider): turn to the driver's door, dive out to the left (+X),
72
+ * shoulder-roll along the ground and stand, turning back to face the original heading.
73
+ */
74
+ export declare const CRASH_PATH: {
75
+ T: number[];
76
+ x: number[];
77
+ yaw: number[];
78
+ pitch: number[];
79
+ drop: number[];
80
+ y: number[];
81
+ floor: number[];
82
+ };
83
+ export declare const CRASH_DURATION = 3.6;
84
+ /**
85
+ * Crash and fall down: thrown out of the driver's door, twisting in the air, landing hard and tumbling onto
86
+ * the back, ending in Get up (from back)'s starting pose about 3 m to the left.
87
+ */
88
+ export declare const CRASH_FALL_PATH: {
89
+ T: number[];
90
+ x: number[];
91
+ y: number[];
92
+ yaw: number[];
93
+ pitch: number[];
94
+ drop: number[];
95
+ z: number[];
96
+ floor: number[];
97
+ };
98
+ export declare const CRASH_FALL_DURATION = 3.4;
99
+ /** Where the occupant ends after leaving a vehicle mid-action: [x scaled to the rider, metres behind it, height change]. */
100
+ export declare const vehicleExit: (clip: string, duration: number) => {
101
+ x: number;
102
+ lift: number;
103
+ behind: number;
104
+ } | undefined;
@@ -0,0 +1,3 @@
1
+ import { VehicleKit } from './vehicle-kit';
2
+ export declare function buildJet(k: VehicleKit): void;
3
+ export declare function buildTank(k: VehicleKit): void;
@@ -0,0 +1,16 @@
1
+ /** Shared rigid transform: both rider and prop roll about the same longitudinal axis. */
2
+ import type { Vec3 } from '../math';
3
+ import { type Q } from '../anim/quat';
4
+ export declare function vehicleStunt(model: string, time: number, duration: number, scale: number): {
5
+ rotation: Q;
6
+ translation: Vec3;
7
+ pivot: Vec3;
8
+ };
9
+ /**
10
+ * The empty vehicle after its driver dives out: it slides on, then rolls one and a half times away from the
11
+ * driver's side and comes to rest upside down. Shares the stunt roll's ground clearance.
12
+ */
13
+ export declare function vehicleCrash(model: string, time: number, scale: number): {
14
+ rotation: Q;
15
+ translation: Vec3;
16
+ };
@@ -0,0 +1,2 @@
1
+ import { VehicleKit } from './vehicle-kit';
2
+ export declare function buildWatercraft(k: VehicleKit): void;
@@ -0,0 +1,49 @@
1
+ /** One fitted, customizable vehicle implementation for preview, films and game exports. */
2
+ import * as T from 'three';
3
+ import { RiderFit } from './vehicle-kit';
4
+ import { type VehicleId, type VehicleStyle } from './vehicles';
5
+ import type { Rig } from '../rig/rig';
6
+ import type { Animator, Frame, BakedClip } from '../anim/evaluate';
7
+ import { type Clip } from '../anim/clips';
8
+ import { type VehicleBody } from './vehicle-bodies';
9
+ import type { MeshData } from '../mesh';
10
+ export declare class Vehicle {
11
+ readonly id: VehicleId;
12
+ readonly clip: Clip;
13
+ readonly fitOptions?: {
14
+ cabinRoof?: number;
15
+ body?: VehicleBody;
16
+ } | undefined;
17
+ readonly group: T.Group;
18
+ readonly fit: RiderFit;
19
+ readonly lift: number;
20
+ private stuntRoot;
21
+ /** Set by Studio, which flies and moves vehicles along the film itself instead of the clip-authored motion. */
22
+ filmMotion: boolean;
23
+ private kit?;
24
+ private bicycle?;
25
+ constructor(id: VehicleId, rig: Rig, animator: Animator, clip: Clip, style: VehicleStyle, fitOptions?: {
26
+ cabinRoof?: number;
27
+ body?: VehicleBody;
28
+ } | undefined);
29
+ update(time: number, frame?: Frame, travelDistance?: number, action?: Clip, parked?: boolean): void;
30
+ private lamps?;
31
+ /** Lamps for driving: 0..1 brake (tail lamps brighten) and 0..1 headlights (night and dusk). */
32
+ setLights(brake: number, headlights?: number): void;
33
+ /** Aircraft state from a film: 0..1 gear retraction and engine throttle (0 idle, 1 take-off power). */
34
+ setFlight(retract: number, throttle: number): void;
35
+ get bounds(): T.Box3;
36
+ private shape?;
37
+ /**
38
+ * A steady box for framing a camera on the vehicle: its shape measured once in its own frame, then moved with it, so
39
+ * spinning wheels and rotors and a pose from the previous frame cannot make a following camera judder.
40
+ */
41
+ get framingBounds(): T.Box3;
42
+ dispose(): void;
43
+ /** Rigid components become separate joints, keeping steering, paddles and wheels editable. */
44
+ asset(): {
45
+ mesh: MeshData;
46
+ rig: Rig;
47
+ bake: (clip?: Clip) => BakedClip;
48
+ };
49
+ }
@@ -0,0 +1,60 @@
1
+ /** Shared vehicle IDs and styling. Geometry and fitting live in vehicle.ts. */
2
+ export declare const VEHICLE_IDS: readonly ['bicycle', 'car', 'sports_car', 'suv', 'motorcycle', 'horse', 'canoe', 'kayak', 'rowboat', 'motorboat', 'helicopter', 'pickup', 'tank', 'jet'];
3
+ export type VehicleId = typeof VEHICLE_IDS[number];
4
+ export declare const VEHICLE_CHOICES: readonly ["none", "auto", "bicycle", "car", "sports_car", "suv", "motorcycle", "horse", "canoe", "kayak", "rowboat", "motorboat", "helicopter", "pickup", "tank", "jet"];
5
+ export type VehicleChoice = typeof VEHICLE_CHOICES[number];
6
+ export declare const VEHICLE_LABELS: Record<VehicleChoice, string>;
7
+ export declare const RIDING_VEHICLES: Readonly<Record<string, VehicleId>>;
8
+ export declare const VEHICLE_FOR_CLIP: Readonly<Record<string, VehicleId>>;
9
+ export declare const VEHICLE_CLIP: Record<VehicleId, string>;
10
+ /**
11
+ * Further bodies built around an existing vehicle's fitted rider; riders, boarding and animation stay those of the
12
+ * base vehicle. A style's `body` picks one for that base vehicle.
13
+ */
14
+ export declare const VEHICLE_BODIES: readonly ['danfo', 'van', 'bus', 'truck', 'keke', 'quad', 'scooter', 'kart', 'saloon', 'muscle'];
15
+ export type VehicleBody = typeof VEHICLE_BODIES[number];
16
+ /** The vehicle whose rider posture, boarding and lift each body borrows. */
17
+ export declare const BODY_BASE: Record<VehicleBody, 'suv' | 'pickup' | 'motorcycle' | 'sports_car'>;
18
+ export declare const VEHICLE_BODY_LABELS: Record<VehicleBody, string>;
19
+ /** The bodies offered for a base vehicle. */
20
+ export declare const bodiesFor: (id: VehicleId) => ("bus" | "danfo" | "kart" | "keke" | "muscle" | "quad" | "saloon" | "scooter" | "truck" | "van")[];
21
+ /** The body a style asks for, when it suits this base vehicle. */
22
+ export declare const bodyFor: (id: VehicleId, style: Pick<VehicleStyle, 'body'>) => VehicleBody | undefined;
23
+ /** A display name for the vehicle a style builds, such as "Danfo minibus" for an SUV ride with that body. */
24
+ export declare const vehicleName: (id: VehicleId, style: Pick<VehicleStyle, 'body'>) => string;
25
+ export declare const VEHICLE_FINISHES: readonly ['matte', 'satin', 'gloss'];
26
+ export declare const VEHICLE_VARIANTS: readonly ['classic', 'sport'];
27
+ export declare const VEHICLE_LIVERIES: readonly ['none', 'stripes', 'racing', 'police', 'taxi'];
28
+ export declare const VEHICLE_LIVERY_LABELS: Record<typeof VEHICLE_LIVERIES[number], string>;
29
+ /** Painted designs a vehicle can carry: closed cars take every design, the go-kart its race number. */
30
+ export declare function liveriesFor(id: VehicleId, style: Pick<VehicleStyle, 'body'>): readonly typeof VEHICLE_LIVERIES[number][];
31
+ /** `livery` adds painted designs (racing stripes, a race number, police or taxi colours); `number` is the race number; `body` swaps in another body for the same rider (see VEHICLE_BODIES). */
32
+ export interface VehicleStyle {
33
+ color: string;
34
+ accentColor: string;
35
+ seatColor: string;
36
+ finish: typeof VEHICLE_FINISHES[number];
37
+ variant: typeof VEHICLE_VARIANTS[number];
38
+ livery?: typeof VEHICLE_LIVERIES[number];
39
+ number?: number;
40
+ body?: VehicleBody;
41
+ }
42
+ export declare const DEFAULT_VEHICLE_STYLE: VehicleStyle;
43
+ /** Factory paint for a newly chosen modern model; preserve colours the user has edited. */
44
+ export declare function vehicleStyleForChoice(choice: VehicleChoice, style: VehicleStyle): VehicleStyle;
45
+ /**
46
+ * Choose a vehicle and optionally one of its further bodies. Factory paint follows the choice unless the user has
47
+ * painted it, and a design the new body cannot carry is dropped.
48
+ */
49
+ export declare function vehicleStyleForBody(id: VehicleId, body: VehicleBody | undefined, style: VehicleStyle): VehicleStyle;
50
+ export declare function sanitizeVehicleStyle(value: unknown): VehicleStyle;
51
+ export declare function isPassengerClip(id: string): boolean;
52
+ export declare function isCar(id: VehicleChoice): id is 'car' | 'sports_car' | 'suv' | 'pickup';
53
+ /** Every supported model/role combination, including both occupants for each car design. */
54
+ export declare const VEHICLE_FITS: {
55
+ id: "bicycle" | "canoe" | "car" | "helicopter" | "horse" | "jet" | "kayak" | "motorboat" | "motorcycle" | "pickup" | "rowboat" | "sports_car" | "suv" | "tank";
56
+ clip: string;
57
+ }[];
58
+ export declare function vehicleFor(choice: VehicleChoice, clip: string): VehicleId | undefined;
59
+ /** Raised cabin/deck floors. Bicycle, motorcycle and horse already have their authored saddle height. */
60
+ export declare function vehicleLift(id: VehicleId, scale: number): number;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Procedural weapon props, modelled in metres in a "weapon frame":
3
+ * firearms: origin at the centre of the pistol grip, +Z down the barrel, +Y up, +X left
4
+ * blades: origin at the centre of the handle, +Y along the blade, +Z toward the edge
5
+ * human.ts maps this frame onto the WeaponR socket (see rig/socket.ts).
6
+ */
7
+ import type { PolyMesh } from '../geometry';
8
+ import type { Material } from '../mesh';
9
+ export declare const WEAPONS: readonly ['none', 'rifle', 'pistol', 'sword', 'knife', 'grenade'];
10
+ export type WeaponId = (typeof WEAPONS)[number];
11
+ export declare const WEAPON_LABELS: Record<WeaponId, string>;
12
+ export declare const isFirearm: (w: WeaponId) => w is "pistol" | "rifle";
13
+ export interface WeaponPart {
14
+ mesh: PolyMesh;
15
+ material: Material;
16
+ }
17
+ export interface WeaponFit {
18
+ /** Distance down the barrel (m) where the support hand holds a rifle. */
19
+ supportZ?: number;
20
+ }
21
+ export declare function buildWeapon(id: WeaponId, fit?: WeaponFit): WeaponPart[];
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Bone-name mapping between the game rig (Mixamo names, which clips are
3
+ * written against) and the other skeleton types.
4
+ */
5
+ import type { RigType } from './skeletons';
6
+ /** Game-rig bone name -> bone in the chosen skeleton (the full MakeHuman rig uses its own names). */
7
+ export declare function boneFor(rig: RigType, name: string): string | undefined;
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Automatic rigging: builds the chosen skeleton on the generated body, gives
3
+ * every vertex of every part (body, clothes, hair, accessories) skin weights,
4
+ * and can re-pose the bind pose from MakeHuman's A-pose into a T-pose.
5
+ */
6
+ import type { AssetLibrary } from '../assets';
7
+ import { type PolyMesh, type Skin } from '../geometry';
8
+ import type { Vec3 } from '../math';
9
+ import { type BoneDef, type RigType } from './skeletons';
10
+ /** 3x3 rotation, column-major: [x axis, y axis, z axis]. */
11
+ export type Mat3 = [number, number, number, number, number, number, number, number, number];
12
+ export interface RigBone {
13
+ name: string;
14
+ parent: number;
15
+ head: Vec3;
16
+ tail: Vec3;
17
+ /** World bind rotation: local Y points along the bone, Z roughly forward. */
18
+ rot: Mat3;
19
+ }
20
+ export interface Rig {
21
+ type: RigType;
22
+ restPose: 'A' | 'T';
23
+ bones: RigBone[];
24
+ /** Hands holding something by a handle (a carried bag): their fingers stay closed in every clip. */
25
+ holds?: ('Left' | 'Right')[];
26
+ /** Equipped model, used by mounted weapon poses; the weapon stays on WeaponR. */
27
+ weapon?: import('../props/weapons').WeaponId;
28
+ }
29
+ export interface RigOptions {
30
+ type: RigType;
31
+ face: boolean;
32
+ }
33
+ export declare function mulMV(m: Mat3, v: Vec3): Vec3;
34
+ export declare function mulMM(a: Mat3, b: Mat3): Mat3;
35
+ export declare const transpose: (m: Mat3) => Mat3;
36
+ export declare function axisAngle(axis: Vec3, ang: number): Mat3;
37
+ /** Bone frame: Y along the bone, Z toward the front (or up for forward-pointing bones). */
38
+ export declare function boneFrame(dir: Vec3): Mat3;
39
+ /** Quaternion [x, y, z, w] from a rotation matrix. */
40
+ export declare function quatOf(m: Mat3): [number, number, number, number];
41
+ export declare function skeletonDefs(lib: AssetLibrary, o: RigOptions): BoneDef[];
42
+ /** Place bones from joint positions (already in output space). */
43
+ export declare function placeBones(defs: BoneDef[], joint: (name: string) => Vec3): RigBone[];
44
+ /** Per base-mesh vertex: top-4 influences in the target skeleton. */
45
+ export declare function baseSkin(lib: AssetLibrary, defs: BoneDef[]): Skin;
46
+ /** Uniform grid over body vertices for nearest-vertex weight transfer. */
47
+ export declare class VertexGrid {
48
+ private pts;
49
+ private cell;
50
+ private cells;
51
+ constructor(pts: Float32Array, mask: (v: number) => boolean, cell?: number);
52
+ private key;
53
+ /** k nearest vertices (searching outward ring by ring). */
54
+ nearest(p: Vec3, k: number): {
55
+ v: number;
56
+ d: number;
57
+ }[];
58
+ }
59
+ /** Assign skin weights to a part: from its base-mesh refs where known, else from the nearest body vertices. */
60
+ export declare function skinPart(m: PolyMesh, base: Skin, grid: VertexGrid, k?: number): Skin;
61
+ /** Skin for a fitted proxy: blend of its three reference vertices. */
62
+ export declare function skinFromRefs(refs: Uint32Array, weights: Float32Array, base: Skin): Skin;
63
+ /**
64
+ * Re-pose the bind pose into a T-pose with linear blend skinning. Mutates the
65
+ * parts' positions and returns the re-posed bones.
66
+ */
67
+ export declare function applyTPose(bones: RigBone[], parts: PolyMesh[]): {
68
+ bones: RigBone[];
69
+ move: (bone: number, p: Vec3) => Vec3;
70
+ };
71
+ /** Local transform of a bone relative to its parent (for exporters / three.js). */
72
+ export declare function localTransform(bones: RigBone[], i: number): {
73
+ t: Vec3;
74
+ R: Mat3;
75
+ };
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Target skeletons. Each bone lists the MakeHuman source bones whose skin
3
+ * weights it absorbs, and which MakeHuman joint marks its head. Bone names
4
+ * follow Mixamo, so Mixamo/Unity Humanoid/Unreal retargeting maps them
5
+ * automatically.
6
+ */
7
+ export type RigType = 'game' | 'game_lite' | 'full' | 'none';
8
+ export interface BoneDef {
9
+ name: string;
10
+ parent: string | null;
11
+ /** MakeHuman joint name for the head (e.g. "upperarm01.L____head"). */
12
+ head: string;
13
+ /** Explicit tail joint (leaf bones); otherwise the first child's head. */
14
+ tail?: string;
15
+ /** MakeHuman bones whose weights map onto this bone. */
16
+ mh: string[];
17
+ }
18
+ /** MakeHuman bone names grouped by role (filled from the actual skeleton). */
19
+ export interface MhBoneSet {
20
+ all: string[];
21
+ }
22
+ export declare function gameSkeleton(mh: MhBoneSet, o: {
23
+ fingers: boolean;
24
+ face: boolean;
25
+ }): BoneDef[];
26
+ /** The full MakeHuman skeleton (163 bones incl. face), weights 1:1. */
27
+ export declare function fullSkeleton(bones: {
28
+ name: string;
29
+ parent: string | null;
30
+ head: string;
31
+ tail: string;
32
+ }[]): BoneDef[];
33
+ export declare const RIG_LABELS: Record<RigType, string>;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Weapon socket: a bone ("WeaponR") parented to the right hand, sitting in the
3
+ * centre of a closed grip. Weapons are modelled in this frame, so an engine can
4
+ * attach any of our weapon props to it with zero offset.
5
+ *
6
+ * Socket frame (from the hand's own joints, so it fits every body):
7
+ * +Y out of the top of the fist (index/thumb side): grip axis, blades point this way
8
+ * +Z toward the knuckles: blade edge / barrel direction
9
+ * +X = Y x Z
10
+ */
11
+ import type { Vec3 } from '../math';
12
+ import type { RigBone } from './rig';
13
+ export interface HandJoints {
14
+ wrist: Vec3;
15
+ index: Vec3;
16
+ middle: Vec3;
17
+ pinky: Vec3;
18
+ thumbTip: Vec3;
19
+ }
20
+ export declare const SOCKET_NAME = "WeaponR";
21
+ export declare function socketBone(h: HandJoints, parent: number, scale: number): RigBone;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Skin roughness map (glTF metallic-roughness layout: roughness in G, metalness 0 in B).
3
+ * Skin isn't evenly shiny: the lips are smooth and slightly glossy, the nose and forehead
4
+ * (the T-zone) a little shinier than the cheeks, with soft transitions and fine variation.
5
+ * Areas are found from the face shapes: the vertices a shape moves most are the ones it is about
6
+ * (pucker = lips, sneer = nose, inner brow raise = forehead). Base-mesh UVs are the same for
7
+ * every character, so the map is built once per library and shared.
8
+ */
9
+ import type { AssetLibrary } from './assets';
10
+ export declare const SKIN_ROUGH = "skin_roughness.png";
11
+ export declare function skinRoughness(lib: AssetLibrary): string;
@@ -0,0 +1,10 @@
1
+ import { type MeshData } from '../core/mesh';
2
+ import { type Rig } from '../core/rig/rig';
3
+ import type { BakedClip } from '../core/anim/evaluate';
4
+ /**
5
+ * `meshless`: skeleton + animation only (no geometry, materials or skin), for
6
+ * per-clip animation files (Unity's model@clip convention).
7
+ */
8
+ export declare function exportFBX(mesh: MeshData, name: string, textures: Map<string, Uint8Array>, rig?: Rig, clips?: BakedClip[], opts?: {
9
+ meshless?: boolean;
10
+ }): Uint8Array;
@@ -0,0 +1,9 @@
1
+ /** Binary glTF 2.0 (.glb) writer with embedded textures. One primitive per material. */
2
+ import { type MeshData } from '../core/mesh';
3
+ import { type Rig } from '../core/rig/rig';
4
+ import type { BakedClip } from '../core/anim/evaluate';
5
+ export declare const mimeOf: (file: string) => "image/jpeg" | "image/png";
6
+ /** `meshless`: skeleton + animations only (per-clip animation files). */
7
+ export declare function exportGLB(mesh: MeshData, name: string, textures: Map<string, Uint8Array>, rig?: Rig, clips?: BakedClip[], opts?: {
8
+ meshless?: boolean;
9
+ }): Uint8Array;
@@ -0,0 +1,22 @@
1
+ import type { AssetLibrary } from '../core/assets';
2
+ import { type Character } from '../core/human';
3
+ import { stemOf, type ExportPlan } from './plan';
4
+ export * from './plan';
5
+ export type ExportFormat = 'glb' | 'fbx' | 'obj' | 'zip';
6
+ export interface ExportFile {
7
+ name: string;
8
+ data: Uint8Array;
9
+ mime: string;
10
+ }
11
+ export declare const fileStem: typeof stemOf;
12
+ /** Execute an export plan: one file, or a zip with exactly the planned files. */
13
+ export interface ExportExtras {
14
+ previewPng?: Uint8Array;
15
+ /** Progress: what is happening and the fraction done (0..1). */
16
+ onProgress?: (label: string, frac: number) => void;
17
+ }
18
+ export declare function runExport(lib: AssetLibrary, ch: Character, plan: ExportPlan, extras?: ExportExtras): Promise<ExportFile>;
19
+ /** Simple one-call export (CLI / tests): GLB / FBX with the character's rig and all clips, OBJ static, ZIP everything. */
20
+ export declare function exportCharacter(lib: AssetLibrary, ch: Character, format: ExportFormat, extras?: {
21
+ previewPng?: Uint8Array;
22
+ }): Promise<ExportFile>;
@@ -0,0 +1,6 @@
1
+ /** Wavefront OBJ + MTL writer. Keeps the original quad topology; textures referenced from `texDir`. */
2
+ import { type MeshData } from '../core/mesh';
3
+ export declare function exportOBJ(mesh: MeshData, name: string, mtlFile: string, texDir?: string): {
4
+ obj: string;
5
+ mtl: string;
6
+ };
@@ -0,0 +1,63 @@
1
+ import type { Character } from '../core/human';
2
+ import { type VehicleId } from '../core/props/vehicles';
3
+ import { type StageProp } from '../core/anim/stage';
4
+ export type ExportMode = 'static' | 'rigged' | 'animated';
5
+ export type FormatChoice = 'glb' | 'fbx' | 'obj' | 'all';
6
+ export interface ExportSettings {
7
+ mode: ExportMode;
8
+ format: FormatChoice;
9
+ /** Clip ids to include (animated mode). */
10
+ clips: string[];
11
+ /** 'embedded': every clip inside the model file. 'separate': model + one file per clip (zip). */
12
+ packaging: 'embedded' | 'separate';
13
+ /** Separate clip files include the mesh (else skeleton + animation only, Unity "model@clip" style). */
14
+ clipMesh: boolean;
15
+ /** Locomotion clips travel (root motion) instead of playing in place. */
16
+ rootMotion: boolean;
17
+ /** Name looping clips "Walk-loop" so Godot imports them as looping. */
18
+ loopSuffix: boolean;
19
+ /** Held weapon: 'held' = in the hand, skinned to the WeaponR bone; 'separate' = its own prop file. */
20
+ weaponFile: 'held' | 'separate';
21
+ /** Include fitted vehicles as independent prop assets. Defaults to true. */
22
+ vehicleFile?: boolean;
23
+ /** Show the ladder, vault obstacle, ledge wall and cover with their clips, and include them as separate prop files. Defaults to true. */
24
+ stageProps?: boolean;
25
+ /** Builder preview action used to fit a static/rigged vehicle prop. */
26
+ vehiclePreviewClip?: string;
27
+ }
28
+ /** Clip name as written into exported files. */
29
+ export declare function exportClipName(id: string, s: Pick<ExportSettings, 'loopSuffix'>): string;
30
+ export declare const DEFAULT_EXPORT: ExportSettings;
31
+ export declare const MODE_LABELS: Record<ExportMode, {
32
+ title: string;
33
+ blurb: string;
34
+ }>;
35
+ export interface PlannedFile {
36
+ /** Path inside the zip (or the download name for single files). */
37
+ path: string;
38
+ kind: 'model' | 'clip' | 'obj' | 'meta' | 'prop' | 'vehicle' | 'stage';
39
+ vehicleId?: VehicleId;
40
+ stageProp?: StageProp;
41
+ /** Fitting pose, including static and rigged vehicle exports. */
42
+ vehicleClip?: string;
43
+ format?: 'glb' | 'fbx' | 'obj';
44
+ rigged: boolean;
45
+ /** Clip ids baked into this file. */
46
+ clips: string[];
47
+ /** Skeleton-only animation file (no mesh). */
48
+ meshless: boolean;
49
+ desc: string;
50
+ }
51
+ export interface ExportPlan {
52
+ settings: ExportSettings;
53
+ /** Effective mode after constraints (e.g. OBJ can't be rigged). */
54
+ mode: ExportMode;
55
+ download: string;
56
+ zipped: boolean;
57
+ files: PlannedFile[];
58
+ notes: string[];
59
+ /** One-line summary for the export bar. */
60
+ summary: string;
61
+ }
62
+ export declare function stemOf(name: string): string;
63
+ export declare function planExport(ch: Character, s: ExportSettings): ExportPlan;
package/package.json CHANGED
@@ -1,15 +1,24 @@
1
1
  {
2
2
  "name": "ara3d",
3
- "version": "0.1.0",
4
- "description": "Generate realistic, rigged and animated 3D characters (GLB, FBX, OBJ) from the command line. Free and open source.",
5
- "keywords": ["3d", "character", "avatar", "glb", "gltf", "fbx", "rigged", "animation", "makehuman", "cli", "gamedev"],
6
- "homepage": "https://ara3dgen.com",
3
+ "version": "0.3.0",
4
+ "description": "Realistic, rigged and animated 3D characters: a three.js library, an <ara-character> embed for any web page, and a command-line tool (GLB, FBX, OBJ). Free and open source.",
5
+ "keywords": ["web-component", "embed", "3d", "character", "avatar", "glb", "gltf", "fbx", "three", "threejs", "rigged", "animation", "makehuman", "cli", "gamedev"],
6
+ "homepage": "https://ara3dgen.com/docs/library/",
7
7
  "repository": { "type": "git", "url": "git+https://github.com/olatunde85/3d-gen.git", "directory": "packages/cli" },
8
8
  "bugs": "https://github.com/olatunde85/3d-gen/issues",
9
9
  "license": "MIT",
10
10
  "author": "Joshua Olatunde",
11
11
  "type": "module",
12
12
  "bin": { "ara3d": "dist/cli.js" },
13
+ "exports": {
14
+ ".": { "types": "./dist/types/packages/cli/src/index.d.ts", "import": "./dist/index.js" },
15
+ "./embed": { "types": "./dist/types/packages/cli/src/embed.d.ts", "import": "./dist/embed.js" },
16
+ "./package.json": "./package.json"
17
+ },
18
+ "types": "./dist/types/packages/cli/src/index.d.ts",
19
+ "sideEffects": ["./dist/embed.js"],
13
20
  "files": ["dist"],
21
+ "peerDependencies": { "three": ">=0.160.0" },
22
+ "peerDependenciesMeta": { "three": { "optional": true } },
14
23
  "engines": { "node": ">=20" }
15
24
  }