OpenUT99-Plus
Unreal Engine 1, rebuilt from scratch
Loading...
Searching...
No Matches
vm.h
Go to the documentation of this file.
1// UnrealScript VM: runs function bytecode from the user's packages (ADR 0006). Spec: docs/formats/script.md (execution)
2#pragma once
3#include <cstdint>
4#include <functional>
5#include <map>
6#include <memory>
7#include <string>
8#include <tuple>
9#include <utility>
10#include <vector>
11
12#include "packages.h"
13#include "upkg.h"
14
15namespace ut {
16
17enum class VT : uint8_t { None, Byte, Int, Bool, Float, Name, Str, Object, Vector, Rotator, Struct };
18
19struct Obj;
20
21struct Value {
23 int32_t i = 0; // Byte, Int, Bool
24 float f = 0; // Float
25 std::string s; // Name, Str
26 Obj* o = nullptr; // Object (nullptr = None)
27 float v[3]{}; // Vector X Y Z
28 int32_t r[3]{}; // Rotator Pitch Yaw Roll
29 std::vector<Value> fields; // Struct members
30 const std::vector<std::string>* field_names = nullptr; // owned by the Vm, one list per struct
31 static Value of(VT t) { Value x; x.t = t; return x; }
32};
33
34// A package object (class, property, texture...) or a script-created instance. Owned by the Vm.
35struct Obj {
36 const Package* pkg = nullptr; // package object: its export; instance: nullptr
37 int32_t ref = 0;
38 Obj* cls = nullptr; // instance: its class (a package object of a class export)
39 Obj* defaults = nullptr; // class object: its default object, built on first use
40 int number = -1; // spawned instance: its name is the class name + this number
41 std::map<const Obj*, std::vector<Value>> vars; // property declaration -> elements
42 // States: the current state, and where its code continues (code of `code_state`, which may be a super state).
43 Obj* state = nullptr;
44 Obj* code_state = nullptr;
45 size_t state_pc = 0;
46 bool code_active = false;
47 float sleep = -1; // latent Sleep: seconds left; < 0 = not sleeping
48 std::function<bool()> wait; // other latent natives: state code resumes once this returns true
49 int state_gen = 0; // bumped by every GotoState, so running code notices a state change
50 std::vector<std::string> disabled; // probe events turned off with Disable (lower case)
51};
52
53enum : uint32_t { kParm = 0x80, kOptionalParm = 0x10, kOutParm = 0x100, kSkipParm = 0x200, kReturnParm = 0x400 };
54enum : uint32_t { kFuncNative = 0x400 };
55
56struct Local { // a property declaration: parameter, return value, local, instance variable or struct member
57 std::string name;
58 int32_t ref = 0; // export ref of the declaration
60 std::string type_name; // property class, or struct name for StructProperty
61 int32_t struct_ref = 0; // StructProperty: the struct (package-local ref)
62 uint32_t flags = 0;
63 int dim = 1;
64 int32_t next = 0; // next field of the same owner
65};
66
67struct Function {
68 const Package* pkg = nullptr;
69 int32_t ref = 0;
70 std::string name;
71 uint16_t native = 0;
72 uint32_t flags = 0;
73 std::vector<Local> locals; // declaration order: parameters, return value, locals
74 std::vector<uint8_t> code; // in-memory form (see skip_script)
75 uint16_t label_table = 0xFFFF; // State: offset of the first label entry (after the 0x0C token); 0xFFFF = none
76 uint32_t state_flags = 0; // State: 0x2 = auto
77};
78
79Function load_function(const Package& p, int32_t ref); // ref: export of class Function
80Function load_state(const Package& p, int32_t ref); // ref: export of class State; locals stay empty
81enum : uint32_t { kFuncIterator = 0x4, kFuncLatent = 0x8, kStateAuto = 0x2 };
82
83class Vm {
84public:
85 using Native = std::function<void(Obj* self, std::vector<Value*>& args, Value& ret)>;
86 explicit Vm(PackageSet* packages); // registers the built-in natives by declared name
87 // Native index -> declaration, from the native functions of p (Core, Engine...).
88 void bind_natives(const Package& p);
89 // Runs f on self (an instance, or nullptr for code that touches no object). args: one per parameter, out
90 // parameters written back. Returns the return value.
91 Value call(const Function& f, Obj* self, std::vector<Value>& args);
92 const Function& function(const Package& p, int32_t ref); // loads and caches; follows imports
93 Obj* object(const Package& p, int32_t ref); // canonical object behind a reference (imports resolved); 0 -> nullptr
94 Obj* spawn(Obj* cls); // new instance with the class defaults
95 Obj* defaults(Obj* cls); // the class default object
96 Obj* super_of(Obj* cls); // super class, or parent state
97 // GotoState: EndState in the old state, BeginState in the new one, then its code runs from label. state "None"
98 // leaves every state, "Auto" picks the class's auto state. Returns false (and logs) if the state is unknown.
99 bool goto_state(Obj* o, const std::string& state, const std::string& label = "Begin");
100 void tick(Obj* o, float dt); // runs state code until it stops, sleeps or changes state
101 // Calls the script function name on o (through its state) if it exists; returns whether it did.
102 bool event(Obj* o, const std::string& name, std::vector<Value>&& args = {}, Value* ret = nullptr);
103 bool event(Obj* o, const std::string& name, std::vector<Value>& args, Value* ret = nullptr); // out parameters written back
104 Value* prop(Obj* o, const std::string& name); // first element of a variable by name; nullptr if none
105 std::vector<Value>* prop_array(Obj* o, const std::string& name); // all elements of a static array
106 void instantiate(Obj* o); // package object (e.g. a map actor) -> live instance: class defaults + its properties
107 void add_native(const std::string& name, Native fn); // by declared name; replaces a built-in one
108 bool is_a(Obj* cls, const Obj* base); // cls is base or a subclass (or a state inside it)
109 Obj* class_of(Obj* o); // an instance's class, or the class of a package object's export
110 std::string name_of(const Obj* o) const;
111 // Iterator natives (ForEach) put the values to visit here; the VM loops over them.
112 std::vector<Value> iterator_items;
113 std::vector<std::vector<Value>> iterator_extra; // optional: per item, values for the further out parameters
114 std::vector<std::string> log; // Log() output and warnings, "Tag: text"
115 std::vector<std::string> trace_calls; // lower-case function names logged as "Call: Class.Function (state)"
116
117private:
118 struct Frame;
119 struct Ref { // assignable place: a value, or one component of a Vector / Rotator; v = nullptr: skipped (None)
120 Value* v = nullptr;
121 int comp = -1;
122 std::vector<Value>* array = nullptr; // the variable's elements, for indexing
123 };
124 struct Bound {
125 const Function* decl = nullptr;
126 const Native* impl = nullptr;
127 };
128 Value eval(Frame& fr, Obj* ctx);
129 Ref lvalue(Frame& fr, Obj* ctx);
130 std::vector<Value>& var(Obj* o, const Package& p, int32_t prop_ref);
131 Value context(Frame& fr, Obj* ctx, bool cls, Ref* place);
132 Value call_native(Frame& fr, const Bound& b, Obj* self);
133 Value call_script(Frame& fr, Obj* target, const Function& f);
134 Value call_named(Frame& fr, Obj* target, const Function& f);
135 const Function* find_virtual(Obj* cls, Obj* state, const std::string& name); // state first, unless nullptr
136 Obj* find_state(Obj* cls, const std::string& name, bool autostate);
137 const Function& state_code(Obj* st);
138 Obj* find_prop(Obj* cls, const std::string& name);
139 void apply_props(Obj* cls, const Package& p, const std::vector<Property>& tags, Obj* target);
140 const Local& decl(Obj* prop);
141 Value zero(const Package& p, const Local& l);
142 void apply_defaults(Obj* cls, Obj* d);
143 void warn(const Frame& fr, const std::string& what);
144
145 PackageSet* packages_;
146 std::map<std::string, Native> by_name_; // lower-case declared name
147 std::map<int, Bound> by_index_;
148 std::map<std::pair<const Package*, int32_t>, Function> functions_;
149 std::map<std::pair<const Package*, int32_t>, std::unique_ptr<Obj>> objects_;
150 std::vector<std::unique_ptr<Obj>> instances_;
151 std::map<const Obj*, int> spawn_counts_; // class -> instances spawned (their name numbers)
152 std::map<const Obj*, Local> decls_;
153 std::map<const Obj*, Obj*> supers_;
154 std::map<std::pair<const Obj*, std::string>, Obj*> props_;
155 std::map<std::string, std::unique_ptr<Obj>> intrinsic_; // classes with no export (Core.Class, Engine.Sound...)
156 std::vector<Ref> iterator_outs_; // out parameters of the last iterator native called
157 std::map<const Obj*, std::vector<std::string>> struct_names_;
158 std::map<std::tuple<const Obj*, const Obj*, std::string>, const Function*> virtuals_;
159 int depth_ = 0;
160};
161
162// UnrealScript names compare without case (ASCII).
163bool iequal(const std::string& a, const std::string& b);
164
165// Axes of a rotator (Pitch, Yaw, Roll; 65536 units per turn) as unit vectors: X forward, Y right, Z up. Local ->
166// world is x * X + y * Y + z * Z (public UE1 rotation matrix, unverified).
167void rotation_axes(const int32_t rot[3], float x[3], float y[3], float z[3]);
168
169} // namespace ut
Definition packages.h:16
std::vector< std::vector< Value > > iterator_extra
Definition vm.h:113
bool is_a(Obj *cls, const Obj *base)
Definition vm.cpp:923
std::string name_of(const Obj *o) const
Definition vm.cpp:904
Obj * super_of(Obj *cls)
Definition vm.cpp:432
Value * prop(Obj *o, const std::string &name)
Definition vm.cpp:529
std::vector< std::string > trace_calls
Definition vm.h:115
Value call(const Function &f, Obj *self, std::vector< Value > &args)
Definition vm.cpp:798
Vm(PackageSet *packages)
Definition vm.cpp:1094
Obj * class_of(Obj *o)
Definition vm.cpp:916
std::vector< Value > * prop_array(Obj *o, const std::string &name)
Definition vm.cpp:534
std::vector< std::string > log
Definition vm.h:114
bool event(Obj *o, const std::string &name, std::vector< Value > &&args={}, Value *ret=nullptr)
Definition vm.cpp:655
Obj * spawn(Obj *cls)
Definition vm.cpp:503
void tick(Obj *o, float dt)
Definition vm.cpp:697
Obj * defaults(Obj *cls)
Definition vm.cpp:490
Obj * object(const Package &p, int32_t ref)
Definition vm.cpp:403
void add_native(const std::string &name, Native fn)
Definition vm.cpp:667
std::vector< Value > iterator_items
Definition vm.h:112
void instantiate(Obj *o)
Definition vm.cpp:539
const Function & function(const Package &p, int32_t ref)
Definition vm.cpp:384
bool goto_state(Obj *o, const std::string &state, const std::string &label="Begin")
Definition vm.cpp:669
void bind_natives(const Package &p)
Definition vm.cpp:393
std::function< void(Obj *self, std::vector< Value * > &args, Value &ret)> Native
Definition vm.h:85
Definition collision.cpp:7
@ kFuncIterator
Definition vm.h:81
@ kStateAuto
Definition vm.h:81
@ kFuncLatent
Definition vm.h:81
@ kFuncNative
Definition vm.h:54
bool iequal(const std::string &a, const std::string &b)
Definition vm.cpp:1337
@ kOutParm
Definition vm.h:53
@ kParm
Definition vm.h:53
@ kOptionalParm
Definition vm.h:53
@ kSkipParm
Definition vm.h:53
@ kReturnParm
Definition vm.h:53
int32_t prop_ref(const Package &p, const Property &prop)
Definition upkg.cpp:219
static Axes rotation_axes(int32_t pitch, int32_t yaw, int32_t roll)
Definition scene.cpp:53
VT
Definition vm.h:17
@ None
Definition vm.h:17
Function load_function(const Package &p, int32_t ref)
Definition vm.cpp:264
@ Int
Definition upkg.h:55
@ Float
Definition upkg.h:55
@ Name
Definition upkg.h:55
@ Vector
Definition upkg.h:55
@ Rotator
Definition upkg.h:55
@ Struct
Definition upkg.h:55
@ Byte
Definition upkg.h:55
@ Bool
Definition upkg.h:55
@ Str
Definition upkg.h:55
Function load_state(const Package &p, int32_t ref)
Definition vm.cpp:273
Definition vm.h:67
const Package * pkg
Definition vm.h:68
std::vector< Local > locals
Definition vm.h:73
uint32_t flags
Definition vm.h:72
int32_t ref
Definition vm.h:69
std::vector< uint8_t > code
Definition vm.h:74
uint16_t label_table
Definition vm.h:75
uint16_t native
Definition vm.h:71
std::string name
Definition vm.h:70
uint32_t state_flags
Definition vm.h:76
Definition vm.h:56
int32_t struct_ref
Definition vm.h:61
int dim
Definition vm.h:63
int32_t ref
Definition vm.h:58
VT type
Definition vm.h:59
std::string type_name
Definition vm.h:60
int32_t next
Definition vm.h:64
uint32_t flags
Definition vm.h:62
std::string name
Definition vm.h:57
Definition vm.h:35
bool code_active
Definition vm.h:46
int number
Definition vm.h:40
int32_t ref
Definition vm.h:37
size_t state_pc
Definition vm.h:45
Obj * state
Definition vm.h:43
std::function< bool()> wait
Definition vm.h:48
const Package * pkg
Definition vm.h:36
std::vector< std::string > disabled
Definition vm.h:50
Obj * cls
Definition vm.h:38
Obj * code_state
Definition vm.h:44
int state_gen
Definition vm.h:49
Obj * defaults
Definition vm.h:39
float sleep
Definition vm.h:47
std::map< const Obj *, std::vector< Value > > vars
Definition vm.h:41
Definition packages.h:11
Definition upkg.h:39
Definition vm.h:21
std::vector< Value > fields
Definition vm.h:29
int32_t i
Definition vm.h:23
std::string s
Definition vm.h:25
static Value of(VT t)
Definition vm.h:31
Obj * o
Definition vm.h:26
int32_t r[3]
Definition vm.h:28
float f
Definition vm.h:24
VT t
Definition vm.h:22
const std::vector< std::string > * field_names
Definition vm.h:30
float v[3]
Definition vm.h:27
Definition vm.cpp:284