Concepts
Starting off
To begin with, it is important to understand how to connect to a server, set your name, and join channels.
The order is important, and you must make sure the step succeeds before you send your next request, as your Client object will usually have checks to make sure the last step was done.
- You must first connect to a server.
- Once On Connect is triggered, you must set your name, using the Set Name action.
You can also request the public channel listing, or send/blast messages directly to the server, but that is all you can do.
> If it fails to connect at all, you will get an On Error event.
> If it connects fine to the server machine, but is denied the connection by the server program, you will get a Connection > On Connect Denied event. - If successful in setting name, Name > On Name Set event is run; from this point on you probably should join a channel using the Channel > Join action.
If denied by server, you will get an Name > On Name Denied event. - If successful in joining a channel, you will get an Channel > On Channel Join event.
If denied by server, you will get an Channel > On Channel Join Denied event.
If this sounds complex, fear not; there is a screenshot of these events in the Examples page.
All these actions can create errors if misused, so make sure you have an event processing errors, no matter how unlikely the error, or how cumbersome it would be to report errors to the user; better to be informative when the program breaks, than do nothing at all and leave the user saying "it doesn't work" and being unable to explain properly how it doesn't work.
Channel/Peer Selection
Just as Fusion has object selection, Lacewing has peer and channel selection.
Conditions that are fired (such as On Message, On Peer Connect, etc, as well as loops) will automatically change your currently selected channel and, for peer-related conditions, your currently selected peer.
You can be connected to multiple channels at once, so it is important to monitor which channel messages are coming from by reading the selected channel expressions (i.e. using Fusion's Compare Two General Values condition).
It is important to first select the channel you will be dealing with right before you deal with it – the same applies to peers.
You can also select peers on the currently selected channel by their peer ID, which is useful for games – you can store a peer's ID with their associated active object. If you have an ID or Name of a peer, you can get the other by selecting the peer and then using the expression you want.
If you're looking for performance, use IDs; they are always 2 bytes, whereas text is null-terminated and can be any length, so it is always faster to find by ID instead of name.
For more detail on selection, see here.
Subchannels
Subchannels are integral values associated with each message you send, be it to the server, to a channel, or to a peer.
The value can be any number in the range 0 to 255, inclusive, and is used per your standards to (often times) differentiate different kinds of information you will be sending. They have no standardization, so you can use the numbers for whatever you please.
For example, you could choose to use subchannel 0 for user chatting messages, subchannel 1 for player movement messages, subchannel 2 for weapon firing messages, subchannel 200 for admin commands, etc.
However, it is recommended to leave server text message 0 for information, and text message 1 for error messages, simply because public servers use that; for example, Darkwire Server 1 has a transfer cap, and will tell users why they're being kicked just before it does so.
If you're using public servers, please read their welcome messages.
It is easiest to think of subchannels as literally being channels within channels.