actions/itgmania212121
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
afa44ee4dfdd47f3ba2bef0453402613ea36f174
itgmania212121/Docs/Userdocs/beginner.txt
T
Martin Natano 15b77ee278 Update documentation
2022-05-28 11:21:13 +02:00

538 lines
24 KiB
Plaintext
Raw Blame History

ITGmania Beginner's Guide
Written and edited by the StepMania team, updated for ITGmania
--------------------------------------------------------------------------------
Table of Contents
1 Introduction
2 ITGmania
2.1. Terms and Concepts
2.1.1 Notable StepMania/ITGmania Versions
2.1.2 ITGmania Components
2.2 ITGmania Configuration
2.2.0 Configuring Keys
2.2.1 Frequently Asked Questions that can be
Solved by Changing the Configuration
2.3. Installing Content
2.3.1 Installing Song Files
2.3.2 Installing Noteskins/New Gametypes
2.3.3 Installing Themes
3. Frequently Asked Questions
4. Reporting problems
================================================================================
Chapter 1: Introduction
================================================================================
Welcome to the ITGmania Beginner's Guide. This guide is primarily meant for
people who do not have any previous experience with ITGmania or StepMania, but
also includes information on how SM5 differs from previous StepMania versions.
================================================================================
Chapter 2: ITGmania
================================================================================
ITGmania is a fork of StepMania 5.1 adding new features for the post-ITG
community.
StepMania is an open-source rhythm game/engine, used by many projects, both
commercial and free.
Some of the things an average StepMania 5 user is expected to know include the
meanings/"proper names" of certain things, as well as how to install content
and configure the program to suit your playing style.
--------------------------------------------------------------------------------
2.1: Terms and Concepts
--------------------------------------------------------------------------------
Like many other video games, ITGmania has a rich lexicon of words which may
confuse others. The most important of the terms has to do with versions of
StepMania, as backwards compatibility is pretty much nonexistent between major
versions.
--------------------------------------------------------------------------------
2.1.1: Notable StepMania/ITGmania Versions
--------------------------------------------------------------------------------
Knowing the versions of StepMania is helpful, as it will help you deduce what
you can and can not install. (Most songs are version-agnostic, though the
background animations may not be. Themes, Noteskins, etc. are tied to
specific versions.)
StepMania 5 is the only version actively supported by the StepMania developers.
All older versions have various problems and/or limitations that make them too
burdensome to continue supporting.
* StepMania 3.9
StepMania 3.9 is the previous stable version of StepMania. It dates back to
2005, and is the version for which the bulk of content is produced.
* StepMania 3.9 Plus/StepMania 3.9 Plus Redux
3.9 Plus/Redux is a fork of StepMania 3.9 that adds features from
later StepMania versions (such as rolls), as well as new features.
* StepMania 3.95/StepMania Online
Generally, when people talk about this version, they refer to a CVS build of
StepMania from around June-August 2006. It was not an officially supported
build of StepMania.
* OpenITG
OpenITG is a fork of the StepMania CVS code from around the time In The Groove 2
was released. OpenITG's goal is to produce a replacement executable for ITG2
machines with enhanced features, though it can also be used at home as well.
* StepMania 4.0 CVS
This term is used to describe versions of StepMania 4 that appeared after "3.95"
up until January 2008, when the last build that could be categorized as "CVS"
was released.
* StepMania 4.0 SVN/alpha
A development version of StepMania. This is the version that sm-ssc was forked
off of. This version is no longer supported and should not be used.
* StepMania 4.0 Beta
Various betas were released for StepMania 4. They are no longer supported, had
various problems, and should not be used.
* sm-ssc
sm-ssc was originally created to provide more theming functionality, as well as
keep the Lua-based StepMania alive (at that point in time, there were plans to
release a version of StepMania based on the old CVS codebase, circa ITG PC).
It eventually became StepMania 5.
* StepMania 5.0 beta 3
The previous beta release of StepMania 5. Includes many features from sm-ssc
and StepMania 4.0 as well as many new features. Any content that works in beta
3 will work in future releases in StepMania 5 (caveat: Many themes made for
beta 3 are full of mistakes, they will not work in beta 4)
* StepMania 5.0 beta 4
The current beta release of StepMania 5. This version has many additional
theming features and bug/crash fixes.
If you wish to port something to StepMania 5, or make a theme for StepMania 5,
it had better work for this version, because it will report your theme
mistakes to you on screen.
* StepMania 5.0.12
The latest stable release of StepMania 5.
* StepMania 5.1 beta 2
The current beta release of StepMania 5.1. It introduced USB profiles and has
become the de-facto standard for StepMania 5 players.
* Project OutFox (aka. Project Moondance, StepMania 5.3)
Currently in alpha. It is a fork of StepMania 5.1 introducing new game modes
and improving software performance. OutFox is scheduled to be released open
source as StepMania version 5.3 in the future, but the source is not available
to the public yet.
* ITGmania 0.5.1
The first release of ITGmania. It's a fork of StepMania 5.1 that focuses solely
on the dance game mode and the needs of the post-ITG community.
--------------------------------------------------------------------------------
2.1.2: ITGmania Components
--------------------------------------------------------------------------------
Despite the title, this is a bit more broader-reaching, as it covers terms that
you may see in StepMania/ITGmania communities and online.
--------------------------------------------------------------------------------
* Courses
Courses exist in many different forms, but in general, they take you through
multiple songs without a break in-between. There are multiple types of courses:
* Nonstop Courses
Nonstop courses use the regular lifebar and typically have 4 songs per
course, though this isn't always the case. It is the easiest of the
course modes.
* Oni/Challenge Courses
The Oni/challenge courses are quite difficult, usually giving you 4 lives
over multiple songs. If you get less than a Great, you lose a life. Once
you lose all your lives, the game is over.
* Survival Courses
Survival courses go by time. Each step judgment is worth something on the
timer, with most of the values being negative by default. If you run out of
time before you complete the course, the game is over.
* Endless Courses
Endless courses are like the name suggests. They don't end until you fail or
decide to quit. Like Nonstop courses, they have a normal lifebar as well.
--------------------------------------------------------------------------------
* Event Mode
Designed to be used during events, this disables the concept of "stages per
game" and lets you play songs until you decide to stop. It is quite useful in
Home Mode, and this guide recommends you enable it.
* Gametypes
Gametypes are the different game modes StepMania can play. They generally
change things like number of default receptors, number of judgments, and more.
Gametypes are directly related to noteskins and unrelated to the different
play modes (Normal, Nonstop, Challenge, and so on).
Examples of gametypes include "dance", "pump", "beat", "techno", and so on.
* NoteSkins
NoteSkins are the appearance of the notes. Most noteskins are bound to certain
gametypes, though some noteskins are easily adapted for other gametypes.
* Pack/packs
A pack is a group of songs for StepMania. The term originated from the
community of StepMania keyboard creators, and can be seen prominently in
certain release names, such as Community Keyboard Mega Pack (CKMP).
When used as a single word question, e.g. "packs?", it is a request for what
packs you have installed.
* Songs
StepMania songs contain a few files, but mainly the steps (.sm, .dwi, .ksf,
.bms, among many other formats) and song file itself (.mp3, .ogg, .wav). In
order to get the most out of StepMania, you'll need to know all about songs
and how to install them.
* Themes
Themes are skins for StepMania. They change the look and feel, and in post-3.9
versions, can also change elements of gameplay (scoring, grading) as well.
StepMania 5.0 adds many features to extend the limits of what a theme can
change.
--------------------------------------------------------------------------------
2.2: ITGmania Configuration
or "How to use the Options Menu"
--------------------------------------------------------------------------------
Learning how to properly configure ITGmania can save you headaches.
Most themes will have the Options menu in plain sight on the Title Menu. In all
versions on StepMania 5 and ITGmania, the options menu can be reached by
pressing the Scroll Lock key at any time. The key set as the "Operator" key in
Config Key/Joy Mappings will also bring up the Service Options menu. Some
people also call this the "service button". Note that in StepMania 5, the theme
can control what options appear on this screen. The information below applies
only to the default theme and themes that choose to present the same options.
The StepMania 5 and ITGmania Options Menu:
* Calibrate Audio Sync
* Select Game
* Config Key/Joy Mappings
* Test Input
* Input Options
* Reload Songs/Courses
* Arcade Options
* Appearance Options
* Set BG Fit Mode
* Graphics/Sound Options
* Profiles
* Network Options
* UI Options
* Advanced Options
* Stepmania Credits
--------------------------------------------------------------------------------
2.2.0: Configuring Keys
--------------------------------------------------------------------------------
Controller mappings in ITGmania are configured in the Config Key/Joy Mappings
screen. To reach it, hit the Operator key (Scroll Lock) and select Config Key/Joy
Mappings from the menu.
The first thing you will see will be a warning telling you not to unmap important
keys, such as the arrow keys and the enter key. This is because those keys are
necessary for navigating the menus, and unmapping them will leave you unable to
navigate the menus. If you accidentally unmap one of the important keys, you can
reset your key configuration to the default by using the "Clear To Default" action.
The warning will be dismissable after 2.5 seconds and will dismiss itself after 5
seconds. (time controlled by theme) After the warning disappears, you will see
the current keybindings, arranged into columns.
Each player has their own three columns. "Primary" and "Secondary" are the two
columns you can configure. "Default" is the column you cannot configure.
The key your cursor is currently on will be flashing between black and white.
(or whatever the theme set it to do)
To set an individual key, move your cursor to the slot you want to set and hit
Enter. The next key you hit will be set in that slot.
To set multiple keys in order, and save time going back and forth between the pad
and the keyboard, move your cursor to a slot and hit 'm'. This marks the slot,
adding it to a list. Hitting 'm' again will remove it from the list. When you have
marked all the slots you want to set, select the "Assign List" option. The screen
will then automatically move through the list of slots in the order they appear
on the screen, setting each one as you press the button for it.
("Assign List" requires you to mark the keys you want because having preset lists
for you to pick from for every game type and the common combinations of what people
will want to set in one go would be more work than it's worth.)
Any changes you make will only be saved when you choose "Save To Disk".
You can reload the settings from the disk with "Reload From Disk".
If you try to leave the screen after changing a key without saving, you will be
prompted to save. Choosing "Yes" will save the settings to the disk and leave the
screen. Choosing "No" will reload the settings from the disk, undoing your change,
and leave the screen. Choosing "Cancel" will do neither, leaving you on the screen.
--------------------------------------------------------------------------------
2.2.1: Frequently Asked Questions that can be Solved by Changing the Configuration
--------------------------------------------------------------------------------
With that in mind, it's time to answer some questions using this knowledge.
Q: How do I play forever, without game overs?
A: Turn on Event Mode in Arcade Options.
Q: What the heck is this thing that says "Toasty" and how do I get rid of it?
A: It's a reference to Mortal Kombat 2, where Dan Forden would pop out from
the side of the screen randomly after an uppercut.
In order to get a Toasty in StepMania, one must get a 250 combo without any
Greats. The number 250 is a reference to how many VS games of MK2 you had to
play before you could play Pong.
As for turning it off, turn Easter Eggs off in the Advanced Options.
--------------------------------------------------------------------------------
2.3: Installing Content
--------------------------------------------------------------------------------
This is the most important section you will read, as all the time that you spend
not playing with ITGmania will be adding/removing things to it. Well, not
completely, as you have other things to do.
Before we touch on the specifics, there are a few skills you should learn.
Previous versions of StepMania had instructions to install things in the main
StepMania folder. This caused problems with UAC on Windows and went against
convention on Linux and macOS. Because of those problems, installing content
in the main StepMania folder is no longer the correct thing to do.
The correct place to install content on ITGmania is the User Data folder.
The exact location is different for each platform.
Windows: %APPDATA%/ITGmania/
Linux: ~/.itgmania/
macOS: ~/Library/Application Support/ITGmania/
Wherever you see the name "User Data folder", this is the folder it refers to.
macOS additionally has ~/Library/Preferences/ITGmania/ for storing preferences.
Inside the User Data folder you can install content by placing it in the following folders:
* Songs
* Themes
* NoteSkins
(and the various gametype folders, which are optional. You need at least one
non-lights gametype in order to play.)
* NoteSkins/dance
* NoteSkins/pump
* NoteSkins/para
* NoteSkins/techno
* NoteSkins/beat
* NoteSkins/popn
* NoteSkins/ez2
* Announcers
(finding announcers made for SM5 is an exercise left for the reader)
* Packages
If one of the folders listed above does not exist, do not worry. You only need
to create a folder if you need to install a piece of content that belongs in it.
* Not on Windows and want to deal with .smzip files?
There are multiple ways to deal this.
1) Put the SMZip file in the Packages folder.
2) Rename the file to have an extension of .zip and extract in the root
User Data folder.
3) Pass the smzip's filename to ITGmania on the command line/terminal.
Dragging and dropping the .smzip may or may not work; we have not tested it.
--------------------------------------------------------------------------------
2.3.1: Installing Song Files
--------------------------------------------------------------------------------
Song files are distributed in many ways. The concept of packs was explained
above, in which multiple songs are included in one archive.
For .smzip files, the section "Not on Windows and want to deal with .smzip
files?" details all possible ways of installing .smzip files, but the most
common ways are as follows:
1) For operating systems with a filetype handler (Windows and macOS), you can double
click on the .smzip file and the ITGmania tools will handle it.
2) Putting the .smzip file in the Packages folder, where it will be automatically
read by ITGmania.
If it's not a .smzip file, you'll have to do some detective work.
Open up the song archive and see how the files are laid out.
The easiest single song installs will have a folder structure similar to this:
Group Name\
Song Name\
song file.sm
song file.ogg/mp3
song file-bg.png
song file-bn.png
With a setup like this, you can just extract it to the Songs folder with
directory structure intact.
Sometimes, simfile authors don't package their file with a group name,
leaving you with a file structure like this:
Song Name\
song file.sm
song file.ogg/mp3
song file-bg.png
song file-bn.png
You will need to extract this into a song group folder that exists already.
An uncommon setup will only include the song files, without any folders at all.
These need to be put into the {Group Name}\{Song Name}\ folder in order to work.
For packs, you follow the same logic. If there are multiple song folders, but no
group folder, you will have to make a group folder. (Flightmix 4 is an example
of a pack that exhibits this behavior.)
Overall, the setup should look something like this:
User Data folder\
Songs\
Song Group 1\
Song Group 2\
Song Group 3\
Song Group 4\
Example Song\
Example Song.sm
Example Song.mp3/ogg
Example Song-bn.png
Example Song-bg.png
--------------------------------------------------------------------------------
2.3.2: Installing Noteskins/New Gametypes
--------------------------------------------------------------------------------
NoteSkins change the appearance of the arrows. They are also linked with getting
other gametypes supported in ITGmania.
The noteskin installation process looks something like this:
User Data folder\
NoteSkins\
(gametype)\
(noteskin for gametype)\
default\
(gametype2)\
default\
"gametype"/"gametype2" etc. can be any one of the following:
dance (typically 4 panels)
pump (typically 5 panels)
para (5 receptors)
techno (4, 5, and 8 panel modes)
beat (5 and 7 key modes with a turntable on each)
popn (5 and 9 line modes)
kb7 (6 or 7 keys depending on when you try to use it)
--------------------------------------------------------------------------------
2.3.3: Installing Themes
--------------------------------------------------------------------------------
Depending on if the theme is packaged in a SMZip or not, you have a few options.
If it is in a .smzip, you can put it in the Packages directory:
User Data folder/
Packages/
MyTheme.smzip
and ITGmania will automatically read it.
On Windows, you can double click on the .smzip file to install it in your user
packages directory. THIS IS NOT RECOMMENDED BECAUSE IT CAUSES CONFUSION.
Since .smzip files are really .zip files, you could also extract them in the
User Data folder.
If the themer has not packaged the theme in a .smzip, then you have to look
inside the archive to see how the directory layout looks.
1) Themes folder
If it has a themes folder when you open it up, extract in the User Data
folder, like you would a .smzip file.
2) Theme name as a folder
This one will have to be extracted in the Themes directory. You will get a
new folder with the files.
3) A bunch of folders + metrics.ini
The themer was lazy; you're going to have to make a folder in the Themes
directory and extract the theme in there. Then go tell the themer that they're a bad person.
When in doubt, read any documentation that comes with the theme for proper
installation instructions.
Do not attempt to use any theme made for a StepMania version older than StepMania 5.
It will not work at all. Only use a theme made for StepMania 5 if you are a
themer and you are working on that theme to make it work with ITGmania.
================================================================================
3: Frequently Asked Questions
================================================================================
Q: How do I keep my background videos/images from being stretched/distorted?
A: ITGmania has a preference for this, the "Set BG Fit Mode" option on the
Service Options screen.
Each column on that screen is a possible setting for the preference.
Each column shows how a background with each of the 3 most common aspect ratios
will look with that setting. The green rectangle in each example shows where the
edge of the screen will cut off the background, and area not covered by the
background will be black. Themes that change the contents of the Service Options
menu might not have Set BG Fit Mode in the Service Options menu, so it is
recommended to change to the default theme to set this option if you do not see
it in the Service Options menu for the theme you are using.
Q: I'm a themer, how do I change the way ScreenSetBGFit looks?
A: First, make sure your metrics allow it to be accessed. If your theme sets the
LineNames metric in the ScreenOptionsService section, add "BGFit" to that metric.
Second, open Themes/_fallback/BGAnimations/ScreenSetBGFit overlay.lua and read
everything in there.
Third, create the screen in your theme using the knowledge gained from step two.
Q: I run multiple versions of StepMania and I don't want to copy all my songs to the new install location.
A: Close stepmania. Look in your User Data folder for Save/Preferences.ini.
On macOS Save/ will actually be under ~/Library/Preferences/ITGmania/.
Open that file in a text editor. Add the full path to your Songs folder to the
"AdditionalSongFolders" setting. If the folder your songs are in is anywhere
under Program Files or anywhere else that UAC interferes with, you will probably
have problems when editing simfiles.
Q: I have thousands of scores in StepMania 3.9, how can I copy them to ITGmania?
A: Create a new profile in ITGmania. The profile's folder will be
"User Data folder/Save/LocalProfiles/000000/" (000000 is the first profile created,
if the new profile is the second profile, the folder name will be 000001, and so forth).
Place your Stats.xml from StepMania 3.9 into the folder for the new profile,
replacing any Stats.xml that is currently there.
Q: I have some scores in one profile and some other scores in another profile, how do I merge them?
A: Hopefully, this feature will be added soon.
Q: I want to make a theme, why do I have to learn Lua? Isn't making a theme just making graphics?
A: Themes are far more powerful in StepMania 5 and ITGmania than in previous
versions. Themes are more than just image files and can change every part of
interacting with StepMania. With this power comes the requirement of knowing
how to use it. If the thought of learning Lua and using it as a language
frightens you, spend more time reading the documentation and asking questions
so you can learn to understand how to use it.
================================================================================
Chapter 4: Reporting Problems
================================================================================
https://github.com/itgmania/itgmania/issues is the bug tracker list.
Use this only for reporting problems or requesting features.
Please search the list before reporting a new issue.
When reporting issues on the bug tracker:
1: Make the title of your issue short and informative.
"Crash report" is a bad title because it doesn't contain any context.
"Crash while juggling kittens" is a good title because it shows vaguely where the
problem is.
2: Include explicit steps for reproducing your problem.
If you can't explain how you encountered the problem, we can't fix it.
3: If you have new information to add to an existing issue, please comment on
that issue with the information you have.
4: Developers have limited time, issues will not be fixed or responded to
immediately. Responses may take a week or two, so be patient and be prepared to
go through a couple requests for more information.
5: It is important to include the name of the theme you are using with any issue
report. If the problem is not an outright crash and cannot be reproduced in the
default theme, it is likely a problem with the theme and should be reported to
the author of that theme. The main StepMania issue tracker is not the place to
report theme problems.
Requesting features on the bug tracker:
If you are a themer requesting a new theme API feature, be prepared to describe
very explicitly what you want. Same as for reporting bugs, be prepared to wait.
If you are a skilled programmer, implementing the feature and submitting a pull
request is a good way to get it added to ITGmania. See github's instructions on
forking a repository and submitting a pull request.
Reference in New Issue View Git Blame Copy Permalink