 |
        |
| >>> LackeyCCG Tutorial, Plugin Creation | ||||||||||||||||||||||||||||||||||||||||||
|
|
Overview In order for a game to be played with LackeyCCG, someone needs to create a plugin for it. Definition: Plugin - a set of a few (mostly optional) files telling Lackey how to set up and configure itself to play a game, as well card data and card image files so Lackey can display the cards in a visually appealing manner. LackeyCCG was initially designed to play Collectable Card Games, but it is also used to play many other kinds of games, like board games and table-top miniatures games like the ones you can find at your local toy store. Throughout the tutorial, I will refer to "cards", but if you are making a game with "pieces" or "figures" instead of cards, just know that the term "card" is generically referring to them as well. This page explains how to create a plugin. There are other (older) plugin formats, but this page will only deal with the latest plugin format (which is the one you should use). The new plugin format is better in a lot of ways than previous versions. One of the major improvements with the new format is it is very hard to make a mistake that screws up your plugin. If you don't do things the right way, your plugin may not work exactly as you want it to, but it will still load and be playable no matter what you do. For the purpose of this tutorial, let's assume you are making a plugin for a CCG called "Zombie". To start, create a folder inside your plugins folder and name it "zombie". (Avoid using spaces in the names of folders and files. Also, keep a plugin name as short as possible.) Create a blank plain text file called plugininfo.txt and put it at <plugin></plugin> Now save plugininfo.txt, and your plugin will now load! You have a single folder, with a single file inside it, with a single line of text on that file, and that is all you have to do to create a functioning (albeit simple) plugin. You may be wondering how, with barely any data input so far, that the plugin will be functional. The secret is default settings. If you don't explicitly define something, Lackey will assume you want to use the default values. For example, say you have a player stat called "Level" and you want it to have an initial value of 0. For all stats, the default initial value is 0, so if you don't explicitly change this, the "Level" stat initial amount will already be 0. You can explicitly define it to be 0, but you doing so is redundant. In general, if you are fine with the default values, your plugin is mostly already made for you. Similarly, if you ever make a mistake and don't define something using the proper syntax, Lackey will assume you want to use the default values. That last reason is why it is hard to screw up a plugin, no matter what you do. In this section I will explain what files are typically included with a plugin, as well as what files are sometimes included, and give a brief description of what those files do. All these files and folders are located in your plugin's folder. For example, for a plugin named "zombie", you would find a file at (LackeyCCG's folder) 
The Main Plugin Info File Since plugininfo.txt is the most important and complicated part of making a plugin, there is an entire page about how to make it. It is linked to here. Card Data File(s) The card data file is where all of a card's information, including Name, Set, ImageFile, and other information about the card is stored.
A card data file is a tab-delimited plain text format file, which can be made with Excel (save it as tab-delimited text). The first row is a line of column headers. The first three columns must be exactly "Name", "Set", and "ImageFile" (no spaces). Beyond that, you can have between 0 and 30 additional columns. If you leave columns blank or do not include them, then LackeyCCG will be unable to display that field's information in the deck editor or in the pop-up card info box during play. Also, without filling in the card data a player will not be able to search for cards that match a specficic field of data. But if you were doing a really quick rush plugin, all you really need is the first 3 columns for it to be playable. Without other card data entered beyond the first 3 columns, people must look at the card images for any information they need. Regarding the first 3 required columns: The Set of a card should match the set name mentioned elsewhere, such as in the packdefinitions file and the formats.txt file. Spaces are not currently allowed in set names, though you can use an underscore (_). The ImageFile column tells LackeyCCG what the name of a card's image file is, EXCLUDING THE ".JPG", which is implicit. You can use other image file formats besides jpg, but if you do, you will need to include the image file suffix in the ImageFile column. (Note in the example above that the .png card image has the suffix included.) Spaces are not allowed in image file names. For cards with unique card backs, you need to do an extra step. In the plugininfo.txt file, you need to include the
ISALLOWINGMULTIPLECARDBACKS argument (which is described on the plugininfo.txt creation tutorial page). A few notes on Card Data files: Excel is a common spreedsheet program that you can use to make the card data file, however it has the very annoying habbit of adding " before and after a column, as well as inserted other junk characters. One workaround for this is to box select (from the top left to the bottom right cells) and the copy to your clipboard. Then, in a plain-text text editor (like wordpad) paste from the clipboard. Them save the text file as your card data file. It's annoying, but it fixes that issue Excel can introduce. If your card entries don't appear in the deck editor as you'd expect, take a careful look at your card data file in a spreadsheet program and make sure all the columns line up like they should. If you break your card data file into multiple files, make sure each has the same number of columns. If you use multiple card data files, Lackey will automatically find all of them that you put in your plugins/zombie/sets/ folder. If you don't want a card data file to be read by Lackey, don't put it in the sets/ folder. It is strongly recommended that you make the (typically) longest field be the right-most column. This is usually the Text column. This makes it look better in the deck editor and in the pop up card text box. The card data file is NOT intended to be a complete database of every possible piece of data about every card. It is strongly suggested that you don't include any unimportant data in your card data file, like the artist's name or "flavor text". These items just take up space and don't really help play the game or construct a deck. If a player wants to see them, he can just look at the image of the card. Only include useful data as columns, and try to combine columns if possible to minimize the number of columns. This makes things easier to read. Batch search/replace can help you clean up your card data file. At the moment weird characters like "ü" are not supported in LackeyCCG. So until they are, please change characters like ü and é to characters like u and e. You should also batch replace to remove extra spaces. Search for a double space, and replace it with a single space. Search for a tab with a space to the left and replace it with just a tab. Search for a tab with a space to the right and replace it with just a tab. Search for "–" and replace it with "-". Manually include Card Data files All card data files that you put in your sets/ folder will be read. If you want only some of the card data files listed there to be considered (and have all others completely ignored), you can create a ListOfCardDataFiles.txt that explicitly lists the card data files you want to have included. All file names listed are assumed to be in the sets/ folder, so you don't need to include any path name. Here is an example of what a ListOfCardDataFiles.txt might look like:
Remember that the listofcarddatafiles.txt file is completely optional. The only reason to include it is if you have old orphaned files (that you may have renamed) and you don't want to use uninstall.txt. The simplest thing for a plugin maker to do is to always use a single file for all card data and never rename it. If you do that, then you will never have any reason to use a listofcarddatafiles.txt. I suggest all card images should be in the jpg format. It is the best image format for both image quality and small file size. All references to image files in the card data file's ImageFile column do not need (and should not have) the .jpg suffix because it is implicit. All card images should be the same size (in dimensions), which is the same size (in dimensions) as the cardback.jpg file. An exception to this is horizontal cards, but their width should should still match the height of the cardback.jpg and vice versa.You can have multiple quality versions of your plugin, each with different card sizes/qualities. Since all card images within a quality version must have the same dimensions, you may want to use a utility like photoshop to batch resize them all so their dimensions are identical. Photoshop can also be used to batch edit cards, doing such things as cropping out a black border on the card, thus allowing the important part of the card image to be larger. Multiple quality versions can be helpful. Computers with smaller monitors or with slow internet connections may want smaller plugins (in dimensions or file size, respectively). And people with larger monitors and fast connections may prefer to have large art. In either case, you should aim for cards to be at least readible from the card image if possible. You can store all image files in a general folder within the setimages folder, or in a folder named after the set within the setimages folder. You always need a cardback.jpg and a spawned.jpg in your plugin's /sets/setimages/general/ folder. You can have multiple card back images if you include ISALLOWINGMULTIPLECARDBACKS:"yes" in your plugininfo.txt file. Add the 2nd image file name after the front image's name with a comma in between. The cell might look like FrontFace,BackFace. If you decide to have some of the cards have unique card backs, not all cards need a unique card back image defined. You are free to mix and match single faced cards (which have the default back) with cards that have unique card backs. The spawned.jpg is used for missing card images or for blank cards which are spawned to the table. I think a good card size for a plugin's card image is about 214x308, but it largely depends on the size of the font on your cards, what is legible, and what looks nice. You might want to make 3 sets of images for 3 different qualities: low, medium, and high. It is up to you. Take a look at what sizes other plugins use and see what size works best for your plugin. LackeyCCG draws several interface elements via image files. There are default images (included in your Lackey folder's images/interface/ folder), but if you define plugin specific images for your plugin, your plugin can override the default interface. To use custom token images, put an image file (preferable a transparent PNG) in your plugin's images folder, adjacent to where you can define phase images. You can define counter images for: You can also define a custom arrow.png and ex.png that are using for marking the table. Note that arrow.png and ex.png should be whitish and not colored. Their color is tinted based on the color of the player who made them. As explained in the plugininfo tutorial, you can also customize the text over image style of card counter display. The default color for text in that style is black, but if you want to use a dark custom counter image, you may want to use a more contrasting font color. Defining Formats in the Deck Editor The formats.txt file allows you to define groups of sets as a "format". These formats can be used to restrict what sets are shown in the deck editor during deck construction. For example, one format may only allow cards from the first 3 sets of your CCG. The content of formats.txt is placed between the <formatdefinitions> and </formatdefinitions> tags. Within those tags, you can define any number of formats, which in turn begin and end with <format> and </format>. There are 2 kinds of values you can input for a format. The label is the name of that format, as it appears in the format filter in the deck editor. In addition, you can add any number of sets between the <set> and </set> tags. Make sure the name of the set listed here matches the name of the set listed in the card data file. Below is an example of an entire formats.txt that includes 2 formats.
Pack definitions allow you to do a number of things. First and foremost, you can allow people to open virtual packs of cards. You can also use this system as an alternate way of packaging preconstructed decks. This system can also be used to randomly generate decks. In short, there are a bunch of uses. How to do this is described in its own tutorial page, which is located here. If you want to save an initial setup of a game state (including specific cards at certain places) you can define this in start.txt. For example, you could define a start.txt file for chess so that every time you selected "New Game" from the menu, all of the chess pieces would be put on the table where they should start. Creating one of these files is very simple. Just set up everything how you want it, and then save the game. Rename that saved game file (which should be in your plugin's saved/ folder) to "start.txt". There is one more step you need to do. Find where it lists the player names in start.txt. For example, say a card on the table was listed as What you need to do is batch find/replace "Trevor" with a generic name for the person in the first seat. Replace "Trevor" with "PLAYER0", so you have: Do the same for any other player names listed in the start.txt file, giving them generic names PLAYER0, PLAYER1, PLAYER2, and so on as needed. In the chess plugin for example, there are only PLAYER0 and PLAYER1. If you want an example of a plugin that uses start.txt, check out the chess plugin. The start.txt file can restore anything that can be saved in a game file, including player stats, cards, the location of cards, the phase of the turn, counters on cards, and many other things. If your game requires a lot of initial setup, defining a start.txt file may make playing a whole lot easier. Plugin makers can add card sounds to plugins that play when cards are sent to the table. The card sounds can also be played explicitly by users. This is a really fun feature. Enabling it is simple. The plugin maker puts sound files in a folder named "sounds" that is in your plugin's forlder. And then the plugin maker makes a new column in the card data file with a header named "Sound". In this column, he puts the sound file names (you can omit the .wav suffix). The corresponding sound will play automatically whenever that card is first placed onto the table. Both you and your opponent will hear it. You can also CTRL+ALT+ mouse click on a card on the table to have it play it's sound explicitly. Or in the deck editor, you can also CTRL+ALT+ mouse click a card, but clicking in the deck editor will not make the sound play for the opponents. (Remember to include your sound files in your updatelist.txt so they are automatically downloaded. Remember that if you zip a file before you upload it, Lackey will automatically unzip it when it is downloaded.) You can also include a file called "ListOfCardSoundFiles.txt" in your plugin's folder. This file will let Lackey smartly pick sounds to play when the Sound column entry is blank for a particular card. To reiterate, this function will not affect any cards for which you have already defined a sound file. This file will not do anything if you have no Sound column in your plugin. Note that more than one of the definitions could apply to a card. For example, if one definition played a "goblin" sound, and another definition played a "warrior" sound, and a card was both a goblin and a warrior, only one of those sounds will play. The first definition listed will be used and all others will be ignored, so when you create your generatesoundcolumn.txt file, keep this fact in mind and sort your definitions accordingly. So if you have a generic sound for character cards, and also specific sounds for specific character cards, make sure you define the specific character card sounds first. The contents of a ListOfCardSound.txt might look something like this:
The file begins and ends with the listofcardsoundfiles tag. You can type anything you want outside of the area between those tags. There are any number of entries inside. Each entry begins and ends with the soundentry tag. Each soundentry tag consists of the sound file name (with .wav being implicit if no suffix is explicitly written), and then an evaluator defintion consisting of a field, eval, and data entry. The evaluator definition consists of a column name (such as "Type"), an evaluator type (such as "CONTAINS" or "IS"), and a data entry. The soundfile and data entries are required, but the field and eval entries can be omitted, in which case they will be assumed to be the default values of "Type" and "CONTAINS", respectively. How to Install and Update your Plugin Automatically An updatelist.txt file is a small text file that you can create that will make it a lot easier for people to install or update your plugin. There are many advantages to using update list files.
Using an updatelist.txt file is easy. Watch the video tutorial on how to install a plugin if you've never installed a plugin.
Here is a sample updatelist.txt file for the zombie test plugin.
There are 3 sections of the updatelist.txt file. The first section is the first line, and it just contains the name of the plugin, followed by a tab, and then the date of the last time this updatelist file was made. (Make sure you write the date in the form of mm-dd-yy.)
The next section is the checksummed file list. This section consists of any number of lines, where each line contains 3 parts, each separated by a tab. The first part is the local path the file should be saved to, relative to the Lackey folder. The second part of each line is the URL from which the file is downloaded. The final part of each line of this section is a checksum for that file. A checksum is a single number which sums up the contents of a file and this number should be unique to that file, differentiating this file from all other files. How you get checksums for files is explained later in this section. Before a proper checksum is generated, just include any number as a placeholder checksum. In summation, the checksummed file list is a way Lackey knows where to get a file from, if it needs to get that file (or if the one it has locally is up to date), and where to save the file to if it downloads. You can use this to install any files into a person's Lackey folder, but you should NOT use this method for the actual card image files because those are handled specially in the 3rd section. Note that cardback.jpg and spawned.jpg files are not considered to be card image files, and you SHOULD include them in the checksummed file list. NOTE: A lot of plugin makers don't seem to get the following concept, so I want to emphasize it. The file/folder hierarchy of the files as they are stored online has NOTHING to do with the file/folder hierarchy with the files once they are downloaded. You could have every single file that is part of your plugin stored remotely online at completely different websites if you wanted to. The file name online does not have to be the name of the file that is downloaded locally. In other words, you can use the updatelist.txt to rename files. YOU define the URL to get the file, and YOU define the destination and file name a file is saved as. A lot of plugin makers just drag and upload their plugin's folder online and this is not a good way to do things. For example, you can store a card data file online in the plugin's main directory, next to plugininfo.txt and the other files, but when the file is downloaded, you can save it to plugins/zombie/sets/carddata.txt where it belongs. Understanding the difference between an online hierarchy and a local hierarchy can make maintaining multiple quality versions of your plugin a lot easier.
The 3rd and final section of the updatelist.txt file contains a method for Lackey to download card image files as needed. There are 3 ways to do this: CardImageURLs or CardGeneralURLs or CardURLFiles. You can use any method, or even all 3 methods, but typically you will only use one method for downloading missing cards.
CardImageURLs entries are defined much like the other files, except they don't use checksums. You can have any number of definitions following the line with "CardImageURLs:". A valid entry (one per line) consists of a local destination path, a tab, and the URL from which to download the file. Since these are all card images, the local destination path is not relative to the Lackey folder, unlike the previous section's local paths were. Rather, the destination path for downloaded card images is relative to your plugin's setimages folder. With CardImageURLs, the <Lackey'sfolder>/plugins/<pluginname>/sets/setimages/ part of the local file path is implicit, so you don't need to type it in for each local destination path of cards. Just put the set name, a "/", and then the local file name the file is saved as. In the above example, the card image from http://this-is-some-URL/samplefolder/set01001.jpg would be downloaded and saved as "d2-x2.jpg" at <Lackey's folder>/plugins/zombie/sets/setimages/firstset/d2-x2.jpg
The CardURLFiles subsection works very much like the CardImageURLs section, except instead of listing all the card image file local and remote paths right there, you put them all in one or more separate files, named CardImageURLs1.txt, CardImageURLs2.txt, etc.
The above could be included in your updatelist.txt file. If you do, make sure you include the files you listed in your checksummed file list in the 2nd section.
The final method for downloading missing card image files is CardGeneralURLs. CardGeneralURLs lets you include a common parent URL that all card images will be looked for in. The huge benefit of the CardGeneralURLs method is that it is very simple. You just put all the card image files in a single folder online, and you just specify that single folder URL. The bad thing about this method is it doesn't let you download card images from multiple different sources, and it doesn't let you rename files. If you DO need to rename some files, or download a few cards from different sources other than the one general URL, you can include a CardImageURLs (or CardURLFiles) in addition to a CardGeneralURLs section. You can use both CardImageURLs and CardGeneralURLs, but LackeyCCG will always attempt to first download using the URL specified explicitly in CardImageURL (if you specify one for that card) before it attempts to use the more general CardGeneralURLs method for that card.
Generating CheckSums Generating checksums is easy. There is a log command for it. Type, in the chat log, "/mkupdate plugins/zombie/updatelist.txt" and hit return. (Use your plugin's name in place of "zombie".) That will generate a new file called updatelistNEW.txt that is identical to updatelist.txt except that it has valid checksums in it. You can then rename the newly created file to "updatelist.txt" and you will have a valid autoupdate file with valid checksums. Once you do that, you are all set to have people install or update your plugin. If you ever update your plugin, just run "/mkupdate plugins/zombie/updatelist.txt" again as before, and upload the updated (or new) files to your website. If you want your plugin added to the pluginfinder, so that anyone may discover your plugin, post about it in the plugin forum of the LackeyCCG forum and I will add it to the list. How to let Lackey automatically check to see if people are using the latest version of your plugin You can include a file called "version.txt" in your plugin that Lackey will use to tell if there is a newer version of the plugin. When Lackey launches, it will look at your plugin's local version.txt file (if you have one) and compare it to the one online. If the one online is newer, the user will be prompted to update their plugin. Every time you update your plugin, you need to update your version.txt file in order to take advantage of this feature. The contents of version.txt look like this:
You need to include the date, in the exact format of YYMMDD. This needs to be 6 characters long, so use zeros if needed. You also tell Lackey what quality version of the plugin they have installed (low, medium, high, or max). If you only have one version, you can omit this. You also need to tell Lackey the URL where you have the remote version.txt. This is the file Lackey will look at to determine if it needs to do an update. You also need to define the updatelist.txt URL from which the actual update is done, if an update is needed. Lastly, you can optionally include a note like "This includes the latest set." or whatever you want to say. Remember that you need to include the remote version.txt file as one of the files to download in your updatelist.txt. Otherwise, Lackey would tell people they always need to update. How to uninstall outdated files You can include a file called "uninstall.txt" in your plugin that Lackey will use to remove outdated files and directories. This includes files that are no longer needed, files that have been renamed, or even card image files for which there is a newer image. All of the path names are relative to your plugin's folder, so you do not need to specify the The contents of uninstall.txt look like this:
The first entry is dateYYMMDD, and this is required. This allows you to specify when this unistall.txt should be ignored. For example, suppose you modified your plugin on June 1st and people who downloaded the plugin since then don't have the now outdated files. If you set your date to <dateYYMMDD>110601</dateYYMMDD>, then only people who have the old outdated files will actually run the uninstall. You can put any number of additional entries which are path names to directories or files. Remember that you can store cardback.jpg and spawned/jpg in several different places, such as adjacent to plugininfo.txt. I point this out because if you wanted to do The uninstall.txt is used only during an autoupdate.
|
|||||||||||||||||||||||||||||||||||||||||
