To use this article requires the following products:
- The Games Factory 2 or greater
And the following extensions:
- OINC Client
And the following optional files:
- TDC Chat Game Source http://sites.google.com/site/jlambsoft/Home/games/tdchatgamesource.mfa
Welcome to my first article! For some reason I've chosen to write it about the OINC client object. This is to teach the basics about the different functions and actions as well as for their uses. This should help people just getting started with OINC for online play and/or chat. It even comes with a bonus section especially about making TDC Chat games!
The OINC Client
The OINC Client is an object for The Games Factory 2 and Multimedia Fusion 2 Standard/Developer allowing communication between applications on remote computers through the internet. It includes a variety of actions and functions to do so. The ones of primary importance are Connect/Disconnect, Set Name, Join/Leave Channel, Set Peer, Send, and Blast.
The Connect action is used to connect to an OINC server. An OINC server will have a url similar to any website url, such as aquadasoft.com or server.klikfarm.com. Not all urls lead to OINC servers and the client will not connect if the url designated does not do so. For any of OINC's actions to work properly it must be connected to a server. The action will call for a server url first, and then a port. The default is 6121, a port not used by many other services. Using this port usually guarantees a clean and strong connection for that reason.
Disconnect can be used once OINC is connected to a server and will disconnect the application. Once you disconnect, you lose your name.
Once OINC is connected to a server, it will require a name for identification on the server. The same name can only be connected to the server once. If the name is already in use when you try to connect you will be denied. Names can be used to communicate with select peers (other users) and identify messages meant specifically for a certain person. Using the action simply calls for a name to be used.
Even after getting a name, you'll still need a channel to communicate on. The purpose of channels is to allow people public or private lanes of traffic for sending and receiving messages. It is possible to connect to multiple channels at once, allowing you to communicate on multiple lanes. The action asks you for a channel name and whether or not the channel will appear on the channel list. The channel list can be called upon by the OINC object to view all active channels, so if you wish your channel to be private from random applications it would be best to hide it.
Leave Channel disconnects you from a channel without disconnecting you from the entire server. If you are connected to multiple channels, you should use the Select Channel action to designate which channel will be left. Otherwise, you will leave the channel most recently used.
Set Peer (And Peers in General)
The Set Peer action is used to select another user by name or ID on the channel. This action is handy for communicating to a certain user or to reference another user in a message. A peer can be set by name or ID.
Every user besides you that is on a channel is called a peer, and every user receives both a name and an ID upon connection. The name is selected but the ID is automatic, and either can be used to single out another user.
The Loop peers action can be used to ask OINC to search the current list of peers, and the On peer loop action can retrieve the name of the peer at the point on the list that OINC is currently viewing. This action is handy for generating a list of the current users on a channel.
Send is OINC's primary method of distributing information to a server, channel, or peer, with separate actions for each target. Three types of messages can be sent: text, number, and stack. Sending a text message will send a string as designated to either the server, channel, or peer (if sending to a peer or on multiple channels, the respective actions must be used to select a target, otherwise it will use the last one selected/used). Sending a number message will only send numbers, no words or other characters. Sending a stack will send any and/or all information currently saved in your stack. Text sending is useful for chatting with others, number sending for basic information, and stack sending for sharing files and data.
Send and blast differ in speed and reliability. Send is a much more trustworthy mode of information sharing but is also slower and will tend to lag a server or channel if you send often.
Blast is OINC's other method of distributing information to a server, channel, or peer and can carry the same kinds of information as Send. Blast is much quicker than Send and is useful for small amounts of data that must be sent often. However, it also fails more often than Send and so should not be used for crucial data sending. Blast is handy for sending information that is important but not crucial, such as an objects position or animation value.
Hints on Using OINC
Remember that only one person can have any one name on any server, so it is best that you have your own private server if using OINC for applications such as chat programs or filesenders based in user databases on a website. In addition, the name can have tags (extra characters) attached to them and parsed out or ignored by the application to preserve the ability to use any name. Furthermore, you can use an encryption object such as Blowfish to encrypt (and decrypt upon use) names for added availability.
If you don't want just anyone joining your channel you can give it an encrypted or tagged name (as with peers) and hide it from the channel list. If you own the server and have control over it, you can set it up to deny certain users from connecting as well.
The Set Peer action calls for a name or an ID, and when sending or blasting messages, it is often handy to have the message include the name of the user who sent it. This way, one can use Left$(), Right$(), or the String Parser object to find the name and identify the sender. Also, there are times when a condition will imply the peer or channel name. Actions involving peers (on peer connect/disconnect or on peer message sent/blasted) or channels (channel message sent/blasted) will have the Peer_Name$(OINC client) function call for the peer who sent the message/connected/disconnected, and the Channel_Name$(OINC client) function call for the channel on which the message was sent/blasted.
Because send is a greater burden on the server, it should be used only for information which is imperative to the app/game use. Information such as position and animation should be blasted, but if another object were to shoot an object, this should be sent so that each person will get the same result (the other user firing a bullet). Also, when sending sensitive information reliant on information previously sent (such as the above bullet being fired by another user) it is best that the initial position and velocity are sent (in the same message) as well, so that if previous blasts containing the user's position have not been received the bullet will still fire from the correct location and in the correct direction.
Blast is important when you need to constantly send information that is not necessarily imperative to the game/app performance. Information such as character position and animation or any other information that references constant events would best be blasted so as not to lag the server.
Games for TDC Chat
To progress beyond this point you will likely require the TDC Chat Game Source file, available here: http://sites.google.com/site/jlambsoft/Home/games/tdchatgamesource.mfa
Game are loaded by TDC Chat through the command /game gamename channel, where gamename is the game's filename excluding the .exe file extension, and channel is the channel on which the game will be played. For games to be loaded properly the file name must not contain any spaces. The game will be loaded by TDC Chat with a command line as such:
gamename.exe /SServer /NName /CChannel /Uchannel
In the command line, Server refers to the server used by TDC Chat, Name refers to the name of the user in TDC Chat, Channel refers to the channel being used in TDC Chat, and channel refers to the channel designated by the /game command. The function CommandItem$() is used to refer to each piece of information. The string within the in the function will designate an item starting after a /, so that calling CommandItem$(S) will return Server and CommandItem$(SSe) will return rver.
To allow the game to use the same name as that in TDC Chat, the name is encrypted using the Blowfish object, and to allow the use of a channel by the same name as the room in TDC Chat, the channel name is encrypted as well. Either name can be interpreted through decryption using the applicable keys. To encrypt or decrypt a string with Blowfish, use:
EncryptString$(Blowfish Object,>encryptionkey<,>stringtobeencrypted< )
DecryptString$(Blowfish Object,>encryptionkey<,>stringtobeencrypted< )
In these functions, >encryptionkey< refers to the string used as a base for encryption and stringtobeencrypted< refers to the string being encrypted or decrypted. For these functions to work properly, the keys in question must be set up before the actual encryption/decryption takes place.
Once the game connects to the requested channel using the requested name, the rest of the coding is up to you!
Hopefully this article has given you a good introduction to the use of the OINC client. If you have any questions you can ask in the comments for this article, and if enough people like it, I might write an article about more of OINC's abilities and/or examples of how to make certain types of games!