You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: lua/actors.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
1
# Actors in Lua
2
2
3
-
The lua plugin has been equipped with a method to utilize the actor subsystem of MQ. This system will allow script writers to communicate between scripts, clients, or even external applications using the same framework that is available [to plugins](../plugins/developing/actors.md). There are some few specializations unique to lua, and this document aims to provide a reference for them. Please refer to the [terminology section](../plugins/developing/actors.md#terminology) in the other actors document for a glossary of terms.
3
+
General Actor documenation available at [Actors](../../main/features/actors.md). Please refer to the [terminology section](../../main/features/actors.md#terminology) in the other actors document for a glossary of terms.
4
+
5
+
The lua plugin has been equipped with a method to utilize the actor subsystem of MQ. This system will allow script writers to communicate between scripts, clients, or even external applications using the same framework that is available [to plugins](../plugins/developing/actors.md). There are some few specializations unique to lua, and this document aims to provide a reference for them.
Actors are a system designed to facilitate simple yet powerful inter-client communication. The underlying technology for local (same computer) communication is Windows Named Pipes, and is very fast -- essentially no different than just using shared memory. Remote communication is ASIO-based TCP communication with a planned UDP discovery mechanism and the ability to specify peers (discovery is still WIP). This provides a system that can connect clients across computers in a network and multiple clients on a local machine simultaneously only opening the minimum number of ports. There is no server in this system, it's peer to peer, but to facilitate local pipe and socket management, the launcher is used as a router on each computer connected to the peer network.
5
+
6
+
## How to Use
7
+
Documentation for the following systems exist in their respective places:
8
+
9
+
-[Plugins](../../plugins/developing/actors.md)
10
+
-[Lua](../../lua/actors.md)
11
+
12
+
Outside of these two interfaces, it is possible to connect to actors from external applications. It would be similar to how a plugin does it, but it is out of the scope of this documentation.
13
+
14
+
The entire system hinges on the launcher (MacroQuest.exe) being present as the central routing mechanism. If the launcher goes down, then all routing will stop and the system will become inoperable.
15
+
16
+
While messaging can use any serialization for internal mailbox communication, protobuf has been utilized to wrap these messages in routing packages to allow for system-independent communication, implicit versioning, and efficient marshalling/unmarshalling. When selecting a serialization strategy, be aware that there are protobuf examples in code and you are probably already building the library.
17
+
18
+
The point of using this technology is to allow for consistent and simple communication between processes that couldn't communicate before. The framework is ideally highly extensible with a minimum amount of boilerplate needed to set up, feedback is welcome.
19
+
20
+
## Terminology
21
+
22
+
-**Actor**: An actor is self-contained computational entity that receives messages and performs actions based on the content of those messages such as side effects and composing replies.
23
+
-**Mailbox**: This is the receiver of messages. Each actor has exactly one, and this provides the unique address for said actor. A mailbox is set up by taking a callback function to process a message.
24
+
-**Dropbox**: This is the sender of messages. Each actor again has exactly one, and this provides automatic return address composition as well as an interface to the application's central Post Office.
25
+
-**Post Office**: The central authority for message routing in a single application. Each independent application will need to set one post office up for actors in that application to register mailboxes. This will maintain ownership of the mailboxes and dropboxes and route all messages received by the application.
26
+
-**Address**: A specifier for routing a message. On the sending side, this does not have to be unique -- one could address a message to all applications that have a certain mailbox, for instance. There are two levels of addressing: mailbox, and postoffice. On the receiving side, the post office must be fully qualified with one of three strategies:
27
+
- By name: You can specify a unique name for an application, which is useful for external application naming. There is one name-specified application that should always be present: `launcher` -- the MQ launcher
28
+
- By pid: You can use the PID of the application (not very useful to the sender as it is not deterministic)
29
+
- By EQ information: The most available of the following three strings: account, server, character. All three of these strings present means that the address must be unique, and this type of addressing replaces name as a convenience mechanism.
30
+
-**Envelope**: This is a protobuf spec that all messages that need to be routed to actors will get wrapped in automatically (as a function of using the Dropbox) so the routing system can ensure it ends up at the correct post offices and mailboxes.
31
+
32
+
## Configuration
33
+
There are two configurations available in [MacroQuest.ini](../macroquest.ini.md) for actors, both dealing with networking. The goal was to keep configuration minimal, but there was need for some slight configuration.
34
+
35
+
In the \[MacroQuest\] section, there is an optional setting `NetworkPeerPort` that lets the user designate the port that the launcher will bind to in order to perform networking peer operations. In most cases, this does not need to be set and the default port of 7781 is fine. Set it if that port is used by another program.
36
+
37
+
The other setting is a complete section in the ini: \[NetworkPeers\]. The entries of this section are simply `host=port`, where a `port` value of 0 just tells MQ to use the default value of port for the peer (set by `NetworkPeerPort` above). An example of this section is as follows:
38
+
39
+
!!!example "[NetworkPeers]"
40
+
```
41
+
[NetworkPeers]
42
+
192.168.4.5=0
43
+
192.168.4.6=8177
44
+
```
45
+
46
+
Where the launcher at the `192.168.4.5` host uses the default port (usually 7781) and the one at `192.168.4.6` has started with the special port of 8177, so we need to tell our local launcher to connect on that port instead. Currently, only IPv4 hosts are supported.
Copy file name to clipboardExpand all lines: plugins/developing/actors.md
+5-25Lines changed: 5 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,26 +1,6 @@
1
1
# How to use Actors
2
2
3
-
Actors are a subsystem added to the MQ ecosystem to allow for different clients and applications to communicate with one another simply. The underlying tech for local (same computer) communication is Windows Named Pipes, and is very fast -- essentially no different than just using shared memory. The tech for remote communication is still WIP and is currently planned to be ASIO-based TCP communication with a UDP discovery mechanism and the ability to specify peers.
4
-
5
-
The entire system hinges on the launcher (MacroQuest.exe) being present as the central routing mechanism. If the launcher goes down, then all routing will stop and the system will become inoperable.
6
-
7
-
While messaging can use any serialization for internal mailbox communication, protobuf has been utilized to wrap these messages in routing packages to allow for system-independent communication, implicit versioning, and efficient marshalling/unmarshalling. When selecting a serialization strategy, be aware that there are protobuf examples in code and you are probably already building the library.
8
-
9
-
The point of using this technology is to allow for consistent and simple communication between processes that couldn't communicate before. The framework is ideally highly extensible with a minimum amount of boilerplate needed to set up, feedback is welcome.
10
-
11
-
## Terminology
12
-
13
-
-**Actor**: An actor is self-contained computational entity that receives messages and performs actions based on the content of those messages such as side effects and composing replies.
14
-
-**Mailbox**: This is the receiver of messages. Each actor has exactly one, and this provides the unique address for said actor. A mailbox is set up by taking a callback function to process a message.
15
-
-**Dropbox**: This is the sender of messages. Each actor again has exactly one, and this provides automatic return address composition as well as an interface to the application's central Post Office.
16
-
-**Post Office**: The central authority for message routing in a single application. Each independent application will need to set one post office up for actors in that application to register mailboxes. This will maintain ownership of the mailboxes and dropboxes and route all messages received by the application.
17
-
-**Address**: A specifier for routing a message. On the sending side, this does not have to be unique -- one could address a message to all applications that have a certain mailbox, for instance. There are two levels of addressing: mailbox, and postoffice. On the receiving side, the post office must be fully qualified with one of three strategies:
18
-
- By name: You can specify a unique name for an application, which is useful for external application naming. There is one name-specified application that should always be present: `launcher` -- the MQ launcher
19
-
- By pid: You can use the PID of the application (not very useful to the sender as it is not deterministic)
20
-
- By EQ information: The most available of the following three strings: account, server, character. All three of these strings present means that the address must be unique, and this type of addressing replaces name as a convenience mechanism.
21
-
-**Envelope**: This is a protobuf spec that all messages that need to be routed to actors will get wrapped in automatically (as a function of using the Dropbox) so the routing system can ensure it ends up at the correct post offices and mailboxes.
22
-
23
-
## In Plugins
3
+
General Actor documenation available at [Actors](../../main/features/actors.md). Please refer to the [terminology section](../../main/features/actors.md#terminology) in the other actors document for a glossary of terms.
24
4
25
5
Plugins are a special case for the actor API as the post office itself is maintained within mq2main.dll and is not exposed at all to any plugins. Instead, plugins will have access to an actor API by including:
26
6
@@ -30,7 +10,7 @@ Plugins are a special case for the actor API as the post office itself is mainta
30
10
31
11
This include provides everything necessary for creating and registering an actor, as well as sending (and receiving) messages. There is one free function (with two overloads) that creates a new actor provided as part of this API:
32
12
33
-
###AddActor
13
+
## AddActor
34
14
35
15
```cpp
36
16
using ReceiveCallbackAPI = std::function<void(const std::shared_ptr<Message>&)>;
@@ -56,7 +36,7 @@ Because the default handling of objects is protobuf, T is assumed to be a protob
56
36
57
37
There are three more structures to explore in a plugin, `Address`, `Message`, and `DropboxAPI`.
58
38
59
-
###Address
39
+
## Address
60
40
61
41
An address is a shim to the protobuf-defined address, and follows the same rules as the [terminology section above](#terminology). The API provides this shim as a simple struct where you can set the address parameters directly like this (as an example):
62
42
@@ -71,14 +51,14 @@ The one difference to note is that there is a member of this address called `Abs
71
51
- If no mailbox is specified at all, then the plugin name becomes the target mailbox.
72
52
- If a mailbox is specified, then the target mailbox becomes `<pluginName>:<mailbox>` as was noted in [the implementation details specified in `AddActor`](#addactor)
73
53
74
-
###Message
54
+
## Message
75
55
76
56
A message consists of 2 parts useful to the plugin author, `Sender` and `Payload`. Both are optional (and are wrapped in `std::optional`), so the author will need to handle the absence of either.
77
57
78
58
-`Sender`: This is the address of the message sender. It's useful if message handling is dependent on the source of the message.
79
59
-`Payload`: This is the actual message payload. It is represented as a string, which is a convenient data storage mechanism that provides bytes and length, and is deserializable directly as a protobuf message. It could be any data that your plugin can handle though, since the handling of it is local to your plugin.
80
60
81
-
###DropboxAPI
61
+
## DropboxAPI
82
62
83
63
This is the object that is returned when an actor is added to the postoffice via the API. The plugin author should store this somewhere where it can be accessed because they will need to use it to send messages and unregister the actor. The object provides the following functions:
0 commit comments