diff --git a/docs/angelscript/game/game-examples.md b/docs/angelscript/game/game-examples.md new file mode 100644 index 0000000..95c1b65 --- /dev/null +++ b/docs/angelscript/game/game-examples.md @@ -0,0 +1,349 @@ +--- +title: Game Examples +weight: 10 +--- + +# Game Examples + +This page contains various examples of how to use AngelScript with Strata Source games themselves. + +To use the examples, create a new file inside the `(game folder)/code` folder (create the folder if it does not exist yet). `game folder` is Strata Source game sepecific, example for Portal 2: Community Edition: `p2ce`. The scripts have to be saved with the extension `.as`. + +Below are examples covering several topics implemented into the latest (as of `5114609d`) Strata Source version for Portal 2: Community Edition. These examples originated from the [StrataSource/sample-content](https://github.com/StrataSource/sample-content) repository and can also be viewed from there under the `code` folder. + +## Client + +### `ConVar Reference` (`client/cvar_ref.as`) + +This script demonstrates ConVar refences. These are the preferred way to interact with ConVars, and the only way to interact with ones registered outside of your script. + +```as +[ClientCommand("cl_example_cvarref")] +void MyCvarRefDemo(const CommandArgs@ args) +{ + ConVarRef intensity("r_portal_light_intensity"); + + Msg("is r_protal_light_intensity valid? " + intensity.GetBool() + "\n"); + Msg("current val: " + intensity.GetFloat() + "\n"); + + intensity.SetValue(1); + Msg("New val: " + intensity.GetFloat() + "\n"); + + ConVarRef invalid_cvar("my_invalid_thingy"); + Msg("is my_invalid_thingy valid? " + invalid_cvar.IsValid() + "\n"); +} +``` + +### `Persistant Storage` (`client/persistent_storage.as`) + +This script demonstrates how to use the persistent storage API. This implementation closely mirrors the VScript implementation, and the two scripting systems share a backend. + +This system may be used to store data in a common area where both VScript and AngelScript can access it. + +> [!NOTE] +> This data is NOT networked and is only stored locally! + +```as +[ClientCommand("cl_example_storage_show", "Example of how to show script storage data")] +void ShowScriptStorage(CommandArgs@ args) +{ + // Create a storage scope that references "myTest" + StorageScope s("myTest"); + + // Display the values + Msg("int " + s.GetInt("int") + "\n"); + Msg("float " + s.GetFloat("float") + "\n"); + Msg("string " + s.GetString("string") + "\n"); +} + +[ClientCommand("cl_example_storage_set", "Example of how to set script storage")] +void SetScriptStroage(CommandArgs@ args) +{ + // Set the values. These will persist across map loads and game restarts, until set or cleared again + StorageScope s("myTest"); + s.SetInt("int", 1234); + s.SetFloat("float", 21.25); + s.SetString("string", "Hello world"); +} + +[ClientCommand("cl_example_storage_clear", "Clear stuff")] +void ScriptStorageClear(CommandArgs@ args) +{ + // Clear all entries in the myTest storage scope + StorageScope s("myTest"); + s.ClearAll(); +} +``` + +### `Persistant Storage` (`client/persistent_storage.as`) + +This script demonstrates how to use the persistent storage API. This implementation closely mirrors the VScript implementation, and the two scripting systems share a backend. + +This system may be used to store data in a common area where both VScript and AngelScript can access it. + +> [!NOTE] +> This data is NOT networked and is only stored locally! + +```as +[ClientCommand("cl_example_storage_show", "Example of how to show script storage data")] +void ShowScriptStorage(CommandArgs@ args) +{ + // Create a storage scope that references "myTest" + StorageScope s("myTest"); + + // Display the values + Msg("int " + s.GetInt("int") + "\n"); + Msg("float " + s.GetFloat("float") + "\n"); + Msg("string " + s.GetString("string") + "\n"); +} + +[ClientCommand("cl_example_storage_set", "Example of how to set script storage")] +void SetScriptStroage(CommandArgs@ args) +{ + // Set the values. These will persist across map loads and game restarts, until set or cleared again + StorageScope s("myTest"); + s.SetInt("int", 1234); + s.SetFloat("float", 21.25); + s.SetString("string", "Hello world"); +} + +[ClientCommand("cl_example_storage_clear", "Clear stuff")] +void ScriptStorageClear(CommandArgs@ args) +{ + // Clear all entries in the myTest storage scope + StorageScope s("myTest"); + s.ClearAll(); +} +``` + +## Server + +### `Entity Iteratiors` (`server/entity_iterator.as`) + +This script demonstrates entity iterators. This system is nearly identical to the VScript system, except that the global object is named differently. + +```as +[ServerCommand("sv_test_entity_iterator", "")] +void EntityIteratorExample(CommandArgs@ args) +{ + // Print a list of all func_brushes in the map + Msg("All func_brushes in this map:\n"); + for (auto@ ent = EntityList().First(); @ent != null; @ent = EntityList().Next(ent)) { + if (ent.GetClassname() != "func_brush") + continue; + Msg(" " + ent.GetEntityIndex() + ": " + ent.GetClassname() + " " + ent.GetDebugName() + "\n"); + } + + // Find the player entity to base our search on + auto@ player = EntityList().FindByClassname(null, "player"); + + if (@player != null) { + Msg("Entities within 128 units of the player:\n"); + + // Search through all entities within 128 units of the player. + // note that we're repeatedly calling FindInSphere, and not using Next() + CBaseEntity@ ent = null; + while ((@ent = EntityList().FindInSphere(ent, player.GetAbsOrigin(), 128)) != null) { + Msg(" " + ent.GetClassname() + " " + ent.GetDebugName() + "\n"); + } + + // Search for func_brush entities within 2048 units of the player + Msg("func_brush entities within 2048 units of the player:\n"); + @ent = null; + while ((@ent = EntityList().FindByClassnameWithin(ent, "func_brush", player.GetAbsOrigin(), 2048)) != null) { + Msg(" " + ent.GetClassname() + " " + ent.GetDebugName() + "\n"); + } + } + else { + Msg("Unable to find player entity\n"); + } +} +``` + +### `Custom Entity` (`server/entity_remove.as`) + +This script demonstrates a custom entity that spawns itself and removes itself when an input is triggered. + +> [!WARNING] +> As of writing for current Strata Source version `5114609d`, outputs for entities are not currently implemented and will not work if defined. + +```as +[Entity("prop_remove_self")] +class PropRemoveSelf : CBaseAnimating +{ + string m_szModelName = "models/gibs/airboat_broken_engine.mdl"; + + void Precache() override + { + PrecacheModel( m_szModelName ); + } + + void Spawn() override + { + Precache(); + SetModel( m_szModelName ); + + SetSolid( SOLID_BBOX ); + + Vector vBounds = Vector( 20, 20, 20 ); + SetCollisionBounds( -vBounds, vBounds ); + } + + [Input("UtilRemove")] + void InputUtilRemove( const InputData &in data ) + { + Msg("Removing ourselves\n"); + + CBaseAnimating@ anim = cast(this); + CBaseEntity@ ent = cast(anim); + util::Remove(ent); + } + + [Input("ClassRemove")] + void InputClassRemove( const InputData &in data ) + { + Msg("Removing ourselves\n"); + + Remove(); + } +} +``` + +### `Game Event System` (`server/game_event_system.as`) + +This script demonstrates how to use the GameEventManager system to fire and listen for game events. + +Game events are optionally networked and are ordinarily used to communicate server data to the client for display on the UI. + +Event networking is unidirectional, always going from server -> client. Events fired on the client-side are not sent to the server. Events on the server may also be fired with the 'bBroadcast' parameter set to false to prevent them from being networked. + +```as +[ServerCommand("sv_firegameevent_server", "")] +void sv_firegameevent_server(const CommandArgs@ args) +{ + GameEvent@ event = GameEventManager().CreateEvent("player_spawn"); + + event.SetBool("BoolValue", true); + event.SetInt("IntValue", 42); + event.SetUint64("UInt64Value", 18446744073709551615); + event.SetFloat("FloatValue", 3.141592); + event.SetString("StringValue", "suspicious imposter"); + + GameEventManager().FireEvent(event); +} + +[ServerCommand("sv_firegameevent_client", "")] +void sv_firegameevent_client(const CommandArgs@ args) +{ + GameEvent@ event = GameEventManager().CreateEvent("player_spawn"); + + event.SetBool("BoolValue", true); + event.SetInt("IntValue", 42); + event.SetUint64("UInt64Value", 18446744073709551615); + event.SetFloat("FloatValue", 3.141592); + event.SetString("StringValue", "suspicious imposter"); + + GameEventManager().FireEventClientSide(event); +} + +[GameEvent("player_spawn")] +void OnPlayerSpawn(const GameEvent@ event) +{ + Msg("Player spawned got fired\n"); + + Msg("We got bool value of: " + event.GetBool("BoolValue") + "\n"); + Msg("We got int value of: " + event.GetInt("IntValue") + "\n"); + Msg("We got uint64 value of: " + event.GetUint64("UInt64Value") + "\n"); + Msg("We got float value of: " + event.GetFloat("FloatValue") + "\n"); + Msg("We got string value of: " + event.GetString("StringValue") + "\n"); + + + Msg("Should be empty: " + event.IsEmpty("DoesNotExistAtAll") + "\n"); + Msg("Should be not empty: " + event.IsEmpty("BoolValue") + "\n"); + + Msg("Is Reliable: " + event.IsReliable() + "\n"); + Msg("Is Local: " + event.IsLocal() + "\n"); +} +``` + +### `Physics Object` (`server/physics_object.as`) + +This script demonstrates how to access and modify physics objects. + +```as +// Applies a random impulse to cubes when you trip and stub your toe +[GameEvent("player_hurt")] +void MyCommand(const GameEvent@ event) +{ + // Find all prop_weighted_cube + CBaseEntity@ ent = null; + while ((@ent = EntityList().FindByClassname(ent, "prop_weighted_cube")) != null) { + Msg("Bumped cube " + ent.GetDebugName() + "\n"); + auto@ obj = ent.GetPhysicsObject(); + if (@obj != null) { + // Wake the object; cubes will go to sleep when powered by a laser or after chillin for a while. + obj.Wake(); + + // Apply random velocity and angular impulse + obj.AddVelocity(RandomVector(-2000, 2000), RandomVector(-5000, 5000)); + } + } +} +``` + +## Shared + +### `Custom Commands` (`server/custom_commands.as`) + +This script demonstrates how to use ServerCommand and ClientCommand attributes to register custom commands. + +```as +#if SERVER +[ServerCommand("sv_example_server_command", "A fun and awesome server command")] +void MyCommand(const CommandArgs@ args) +{ + Msg("This is my server command, called from the server\n"); +} +#endif + +#if CLIENT +[ClientCommand("cl_example_client_command", "A fun and awesome cheat client command", FCVAR_CHEAT)] +void MyClientCommand(const CommandArgs@ args) +{ + if (args.ArgC() < 2) + Msg("Woah, pass more args to see something epic!"); + else + Msg("Arg0 " + args.Arg(0) + ", Arg1 " + args.Arg(1)); +} +#endif +``` + +### `Core Events Types` (`server/init_events.as`) + +This script demonstrates/tests various core event types. These are invoked during the game init process. + +```as +[LevelInitPreEntity] +void OnLevelInitPreEntity() +{ + Msg("level init pre-entity\n"); +} + +[LevelInitPostEntity] +void OnLevelInitPostEntity() +{ + Msg("level init post-entity\n"); +} + +[LevelShutdownPreEntity] +void OnLevelShutdownPreEntity() +{ + Msg("Level shutdown pre-entity\n"); +} + +[LevelShutdownPostEntity] +void OnLevelShutdownPostEntity() +{ + Msg("Level shutdown post-entity\n"); +} +``` diff --git a/docs/angelscript/hammer/classes.md b/docs/angelscript/hammer/classes.md index 65bded1..118fa44 100644 --- a/docs/angelscript/hammer/classes.md +++ b/docs/angelscript/hammer/classes.md @@ -1,5 +1,6 @@ --- title: Classes +weight: 20 --- # Classes diff --git a/docs/angelscript/hammer/enums.md b/docs/angelscript/hammer/enums.md index 940f0d3..38a9d22 100644 --- a/docs/angelscript/hammer/enums.md +++ b/docs/angelscript/hammer/enums.md @@ -1,5 +1,6 @@ --- title: Enums +weight: 30 --- # Enums diff --git a/docs/angelscript/hammer/global-functions.md b/docs/angelscript/hammer/global-functions.md index f8c462c..73b8f85 100644 --- a/docs/angelscript/hammer/global-functions.md +++ b/docs/angelscript/hammer/global-functions.md @@ -1,60 +1,61 @@ --- title: Global Functions +weight: 40 --- # Global Functions This page outlines the various Strata Hammer AngelScript global functions. -### `FindMaterial` +## `FindMaterial` ```as Material@ FindMaterial(const string&in name) ``` -### `GetDefaultTextureName` +## `GetDefaultTextureName` ```as string GetDefaultTextureName() ``` -### `abs` +## `abs` ```as float abs(float) ``` -### `acos` +## `acos` ```as float acos(float) ``` -### `asin` +## `asin` ```as float asin(float) ``` -### `atan` +## `atan` ```as float atan(float) ``` -### `atan2` +## `atan2` ```as float atan2(float, float) ``` -### `ceil` +## `ceil` ```as float ceil(float) ``` -### `closeTo` +## `closeTo` ```as bool closeTo(float, float, float = 0.00001f) @@ -62,25 +63,25 @@ bool closeTo(float, float, float = 0.00001f) bool closeTo(double, double, double = 0.0000000001) ``` -### `cos` +## `cos` ```as float cos(float) ``` -### `cosh` +## `cosh` ```as float cosh(float) ``` -### `floor` +## `floor` ```as float floor(float) ``` -### `fpFromIEEE` +## `fpFromIEEE` ```as float fpFromIEEE(uint) @@ -88,7 +89,7 @@ float fpFromIEEE(uint) double fpFromIEEE(uint64) ``` -### `fpToIEEE` +## `fpToIEEE` ```as uint fpToIEEE(float) @@ -96,85 +97,85 @@ uint fpToIEEE(float) uint64 fpToIEEE(double) ``` -### `fraction` +## `fraction` ```as float fraction(float) ``` -### `getExceptionInfo` +## `getExceptionInfo` ```as string getExceptionInfo() ``` -### `join` +## `join` ```as string join(const string[]&in, const string&in) ``` -### `log` +## `log` ```as float log(float) ``` -### `log10` +## `log10` ```as float log10(float) ``` -### `pow` +## `pow` ```as float pow(float, float) ``` -### `print` +## `print` ```as void print(const string&in) ``` -### `rint` +## `rint` ```as float rint(float) ``` -### `sin` +## `sin` ```as float sin(float) ``` -### `sinh` +## `sinh` ```as float sinh(float) ``` -### `sqrt` +## `sqrt` ```as float sqrt(float) ``` -### `tan` +## `tan` ```as float tan(float) ``` -### `tanh` +## `tanh` ```as float tanh(float) ``` -### `throw` +## `throw` ```as void throw(const string&in) diff --git a/docs/angelscript/hammer/global-properties.md b/docs/angelscript/hammer/global-properties.md index cc0500c..df1e57c 100644 --- a/docs/angelscript/hammer/global-properties.md +++ b/docs/angelscript/hammer/global-properties.md @@ -1,30 +1,31 @@ --- title: Global Properties +weight: 50 --- # Global Properties This page outlines the various Strata Hammer AngelScript global properties. -### `vec3_angle` +## `vec3_angle` ```as const QAngle vec3_angle ``` -### `vec3_invalid` +## `vec3_invalid` ```as const Vector vec3_invalid ``` -### `vec3_origin` +## `vec3_origin` ```as const Vector vec3_origin ``` -### `vec4_origin` +## `vec4_origin` ```as const Vector4D vec4_origin diff --git a/docs/angelscript/hammer/example.md b/docs/angelscript/hammer/hammer-examples.md similarity index 96% rename from docs/angelscript/hammer/example.md rename to docs/angelscript/hammer/hammer-examples.md index 6b1eda2..7b9d2c9 100644 --- a/docs/angelscript/hammer/example.md +++ b/docs/angelscript/hammer/hammer-examples.md @@ -1,12 +1,13 @@ --- -title: Examples +title: Hammer Examples +weight: 10 --- -# Examples +# Hammer Examples This page contains various examples of how to use AngelScript to create new brush types in the Strata Hammer Editor. -To use the examples create a new file inside the `hammer/scripts` folder (create the folder if it does not exist yet). The scripts have to be saved with the extension `.as`. Afterwards, the new brush types can be used by first selecting the `Block Tool` within Hammer and then changing the `Categories` combo-box in the right bar to `Scriptable`. The combo-box `Objects` below then contains the new scripted brushes. +To use the examples, create a new file inside the `hammer/scripts` folder (create the folder if it does not exist yet). The scripts have to be saved with the extension `.as`. Afterwards, the new brush types can be used by first selecting the `Block Tool` within Hammer and then changing the `Categories` combo-box in the right bar to `Scriptable`. The combo-box `Objects` below then contains the new scripted brushes. ## `ExampleWedge` (`script_wedge.as`) @@ -294,7 +295,6 @@ class ExampleWedge : ScriptSolid }; ``` - ## `ExampleSpike` (`script_spike.as`) ```as diff --git a/docs/angelscript/hammer/meta.json b/docs/angelscript/hammer/meta.json index 740a105..8ba2ef9 100644 --- a/docs/angelscript/hammer/meta.json +++ b/docs/angelscript/hammer/meta.json @@ -1,3 +1,5 @@ { - "title": "Hammer" + "title": "Hammer", + "type": "angelscript", + "weight": 10 }