northwood-studios/nwpluginapi

Official server-side plugin system for SCP: Secret Laboratory game.

Nw Plugin API

Official server-side plugin system for SCP: Secret Laboratory game.

Documentation can be found here.

nwpluginapi's Issues

Wrong arguments in PlayerInteractLocker

[2022-12-15 00:48:45.131 +00:00] [Error] [PluginAPI] Event OnInteractWithLocker (PlayerInteractLocker) in plugin MyPlugin.Plugin contains wrong parameters
                                  - Player, Locker, Byte, Boolean
                                  - Required:
                                  - IPlayer.

I used the github template and only changed MyPlayer to Player.

RoundEnd event should have info on how the round ended

I would like these things for scpdiscord, and an enum saying who won would also be nice.

Add response message to command events

Can't register events in a separate event handler

Registering events is only currently possible if handlers are in the same place as plugin entry point. It's not possible to register events in separate handlers.

Some hotkeys are not being fired on hotkeypressed event

The most important for me that don't fire:

VoiceChat
AltVoiceChat
RemoteAdmin
PlayerList
CharacterInfo
GameConsole
HideGUI
NoClipFogToggle
DebugLogMenu
PauseMenu

Event 99 is not registered in manager

[Suggestion] Documentation

Basically it would be nice to document not only the api but Assembly-CSharp and release their documentation xml files somewhere.

PlayerCheckReservedSlot return value doesn't seem to work

When I run return PlayerCheckReservedSlotCancellationData.Override(true); in the event, it still sends the server is full message.

[Suggestion] having a property for sound

SoundAmplitude or SoundVolume would return
0 if no sound and 1 if the sound is very loud
0.5 would be like player talking quietly

Player should have userID, raw userID and userID type

Something like:
UserID: 76561198022373616
UserID type: STEAM
Raw userID: 76561198022373616@steam

Plugin/Event Priority

There should be a priority to how events are executed. Some plugins might want to go first, and others last. For example, a gamemode plugin might want to run first to prevent incompatibilities with other plugins, and a logging plugin might want to go last to make sure it logs what actually happens.

Oban event (or event for all bans)

There isn't any event to see offline bans. I think the best case would be to have a banned event that passes in a nullable player + issuer, plus the ban details.

Event 99 is not registered in manager

I have registered the event(PlayerInteractDoor) as it is in the github examples and in the console it shows this error:

[Error] [PluginAPI] Event 99 is not registered in manager! ( create issue on github )

Suggestion: synchronize NoclipFog with server side

It is needed to force re-enable player's NoclipFog if server disables noclip on server side.

More events

106 events:

• PlayerPocketDimensionEnter
• PlayerPocketDimensionLeave
• PlayerPocketDimensionDie

Others:

• PlayerSetNickname(Player player, string oldName)
• PlayerThrowGrenade - Preferably allowing the plugin to change things like direction and throwing power
• PlayerInfect - Things like amount of damage and time they will be infected would be useful.
• ServerNameSet
• OnSummonVehicle - Whenever the helicopter or car is summoned
• OnPlayerTriggerTesla
• On079UseElevator

Add Player.Items

If it could be a list with just the items I would be grateful :)

Wrong generic constraint in EventManager

Type constraint is incorrect.

NwPluginAPI/NwPluginAPI/Events/EventManager.cs

Line 256 in 98f6834

public static void RegisterEvents<T>(object plugin) where T : Type

Should be

public static void RegisterEvents<T>(T plugin) where T : class

Explicitly define enum values

For the sake of plugin compatibility between releases, enum values should be explicitly defined. This is because any changes other than adding a new enum members to the end of an enum will cause a plugin to use the incorrect enum member unless it is recompiled, which can be very bad. To solve this, enum values should be explicitly defined, especially for enums in the API but also for commonly used enums outside of it (e.g., RoleType, ItemType).

Allow viewing leading team on round end

I'd like to see what team won when the round ends. Preferably as an event argument.

Make RegisterEvents public

NwPluginAPI/NwPluginAPI/Events/EventManager.cs

Line 256 in 53d5933

public static void RegisterEvents<T>(object plugin) where T : class

only allows us to provide a class, we can't pass an existing instance of a class to it. We could pass existing instances if

NwPluginAPI/NwPluginAPI/Events/EventManager.cs

Line 272 in 53d5933

static void RegisterEvents(Type plugin, object eventHandler)

was public

Role and Team should be part of API

Something like this or just include the role and team ids from base game: https://github.com/ServerMod/Smod2/blob/master/Smod2/API/Role.cs

Doc

Where can we find the doc?

Suggestion: new events

Updated requested events list:

SCP079Interaction
SCP914ChangeKnob
SCP914Activate
PlayerInteractDoor
RoundSpawnRoles (so we can alter player roles on round start automatically)
ReinforcementArrive
ReinforcementPrepare

Scp914Activate, Scp914KnobChanged and PlayerInteractDoor are not registered in the event manager

Allow viewing cancelled events

I think cancelled events should be viewable by plugins. They should also be able to un-cancel events.

Making events fully cancellable by plugins can lead to some issues. I think a good example is the difference between cancelling and handling.

Say, for example, we have a command system that works by having an CommandExecuted event. It's been established that this is only for handling commands. In this case, the expectation is that the plugins send some response. Furthermore, they shouldn't send duplicate responses. One way of doing this might be with a Handled property somewhere. As soon as one of the plugins handles the command (and so Handled is true), there's no reason to continue, because it's already been handled.

But this isn't how plugin events work.

Consider the case of a similar event, CommandRan. I'm giving them different names, but they're effectively the same. The difference is that CommandRan isn't meant for executing commands. Rather, it's meant for letting the plugins do something, anything, when a command is ran. It might also have a Cancelled property. If we handle this cancellation the same as handle above, then one plugin may use the event to create a command. When they see the command, they send a response and cancel the event. That's all well and good, but what happens if another plugin comes in and wants to log every command that's ran. Because the previous plugin cancelled, this plugin just won't see the event, and will log incorrectly.

I think the solution to this is to allow plugins to view if an event is cancelled, and maybe also uncancel it. In this case, our first plugin can respond to the user and set it to cancelled. Then, our second plugin will see the event (and that it was cancelled), but will still be able to log it. If any other plugins comes in and tries to respond to the user after the first plugin already did, it can check if the event was cancelled, and if so, not do anything.

Side note: Plugins should use the actual command system. This is just an example. Also, plugin/event priority would help fix this, but maybe the logging plugin wants to always run last (maybe to see if the event was marked as cancelled).

Add throwing player and hit players to OnGrenadeExplosion

Player::Get(UserId) does not work as intended

Player::Get(UserId) always returns null, even if the userid specific is in the game.

It appears that players never get aded to the PlayerUserIds dictionary which is supposed to happen in EventManager::ExecuteEvent which does not appear to happen.

Add PlayerBanning and PlayerKicking Events and a way to prevent them

Currently, there are events to handle players that have already been banned or kicked. But for the purposes of certain plugins, particularly ones that use an online web panel and API, there needs to be a way to run logic before a ban or kick and a way to prevent it. Currently, the only solution is to unban someone immediately after they get banned, which is inconvenient.

Add PlayerSetNickname event

• Player player
• string oldName

Player Damaged event should provide a StandardDamageHandler instead of a DamageHandlerBase

This makes it easier to get the damage value and all damage types inherit from StandardDamageHandler anyway so there is no need to be more generic.

Project Structure

The project structure is very wrong, it is based on wrappers for the main classes.

The structure it should have is just implement the api into the main classes, this won't only provide a higher maintainability but readability and stability.

Pls add to SCP079Generator

// <smod>
public bool Open
{
	get => HasFlag(_flags, GeneratorFlags.Open);
	set => ServerSetFlag(GeneratorFlags.Open, value);
}

public bool Unlocked
{
	get => HasFlag(_flags, GeneratorFlags.Unlocked);
	set => ServerSetFlag(GeneratorFlags.Unlocked, value);
}

public float TimeLeft => (float)_leverStopwatch.Elapsed.TotalSeconds - _leverDelay;

public float ActivationTime => _leverDelay;
// </smod>

Warhead.Start throws NRE

Server.Instance is null

During Runtime, the Server.Instance return null, which causes any Player.SendBroadcast call to fail with NullRef.

System.NullReferenceException: Object reference not set to an instance of an object
                                   at PluginAPI.Core.Player.SendBroadcast (System.String message, System.UInt16 duration, Broadcast+BroadcastFlags type, System.Boolean shouldClearPrevious)

I'm using version 12.0.0-beta9

The API uses Server.Instance.GetComponent<Broadcast> in the SendBroadcast function but bc command uses Broadcast.Instance. This can be used as a WorkAround

Missing object as event argument for some events

ServerEventType.ItemSpawned
ServerEventType.PlayerChangeItem
ServerEventType.PlayerInteract events

Server.RunCommand should return the command's feedback string

Byte is not enough for port

It's better to change port type to ushort

NwPluginAPI/NwPluginAPI/Events/IEventCancellation.cs

Line 49 in 5b01684

public static PreauthCancellationData RejectRedirect(byte port, bool isForced) => new PreauthCancellationData(RejectionReason.Redirect, isForced, port: port);

Add setrank function to the player class

Basically this but with the group part fixed. You could simply make the permissions handler public in the game and use this exact code.

public static void SetRank(this Player player, string color = null, string text = null, string group = null)
{
	ServerRoles roleComponent = player.ReferenceHub.serverRoles;

	if (roleComponent != null)
	{
		// TODO: Fix vanilla ranks
		if (group != null)
			roleComponent.SetGroup(ServerStatic.PermissionsHandler.GetGroup(group), false);
		if (color != null)
			roleComponent.SetColor(color);
		if (text != null)
			roleComponent.SetText(text);
	}
}

Broken plugin config will prevent server from starting

Add RefreshMainBools() on Server.FriendlyFire

Changes to FriendlyFire value do not occur unless ServerConfigSynchronizer.Singleton.RefreshMainBools() is done.

Add IsLocked in Warhead

I don't want them to be able to disable the auto warhead. For now I will use

private static AlphaWarheadController Controller;
Controller.IsLocked = true;

Add ThrowGrenade event

Preferably allowing the plugin to change things like direction and throwing power

Add PlayerInfect event

Things like amount of damage and time they will be infected would be useful.

Add 106 events

• PlayerEnterFemurBreaker
• PlayerContain106 (Specifically when someone presses the button)
• Player106Teleport
• Player106CreatePortal
• PlayerPocketDimensionEnter
• PlayerPocketDimensionLeave
• PlayerPocketDimensionDie (?)

Not sure about the last one, we had it in smod but I can't really see how it is useful in comparison to the normal death event.

Missing way to deny events

Adding IsAllowed or Cancel() to events that can be prevented, ex. ServerEventType.PlayerDeath or ServerEventType.PlayerDamage

Server.RunCommand should take a sender parameter type included in the API so it doesn't depend on Assembly-CSharp.dll

As Server inherits from the Player class this should be fine.

Invalid cast exception after first eventhandler of event with multiple handlers fires

Which leads back to

in EventManager::ExcuteEvent

the method in question calls

which seems to replace elements with the Player object for that handler. (error occurs on the highlighted text)

It seems like the args array is being reused, but Player objects cannot be casted back to (igamecomponent) so it throws an exception

If ToArray is called on the args array everything works as expected, this is likely due to that ToArray creates a copy of the array, which means changes done by RegenerateParameters do not affect the other handlers as each has their own copy of the array.

Add PlayerUseConsumable or edit PlayerItemUse event

Basically adding effect information like these:

TeamRespawn event should have a list of the players spawning in

Paths.Config and Paths.Global don't seem to ever be set

Noticed they weren't set when I tried to use them and it doesn't seem like there is even any code to do it unless it is elsewhere.