actions/itgmania212121
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Martin Natano
2022-05-28 11:21:13 +02:00
parent be0dee1402
commit 15b77ee278
36 changed files with 133 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/Userdocs/Keymaps_ini_format.md
+3 -5
View File
@@ -9,11 +9,9 @@ prevents mapping keys through the Config Key/Joy Mappings screen.
## Location
Windows: %APPDATA%/StepMania 5.1/Save/Keymaps.ini
Linux: ~/.stepmania-5.1/Save/Keymaps.ini
OS X: ~/Library/Preferences/StepMania 5.1/Save/Keymaps.ini
(OS X location may be incorrect, report it if you use OS X and that location
is incorrect)
Windows: `%APPDATA%/ITGmania/Save/Keymaps.ini`
Linux: `~/.itgmania/Save/Keymaps.ini`
macOS: `~/Library/Preferences/ITGmania/Keymaps.ini`
## Structure
Docs/Userdocs/sm5_beginner.txt → Docs/Userdocs/beginner.txt
+79 -131
View File
@@ -1,13 +1,13 @@
StepMania 5 Beginner's Guide
Written and edited by the StepMania team
ITGmania Beginner's Guide
Written and edited by the StepMania team, updated for ITGmania
--------------------------------------------------------------------------------
Table of Contents
1 Introduction
2 StepMania
2 ITGmania
2.1. Terms and Concepts
2.1.1 Notable StepMania Versions
2.1.2 StepMania Components
2.2 StepMania Configuration
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
@@ -15,21 +15,21 @@ Table of Contents
2.3.1 Installing Song Files
2.3.2 Installing Noteskins/New Gametypes
2.3.3 Installing Themes
3. StepMania 5
3.1 Frequently Asked Questions about StepMania 5
3. Frequently Asked Questions
4. Reporting problems
================================================================================
Chapter 1: Introduction
================================================================================
Welcome to the StepMania 5 Beginner's Guide. This guide is primarily meant for
people who do not have any previous experience with StepMania, but also includes
information on how SM5 differs from previous StepMania versions. If you already
know what StepMania is, and the basics of adding things to an install, you can
skip ahead to Chapter 3: StepMania 5. Otherwise, read on.
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: StepMania
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.
@@ -40,13 +40,13 @@ and configure the program to suit your playing style.
--------------------------------------------------------------------------------
2.1: Terms and Concepts
--------------------------------------------------------------------------------
Like many other video games, StepMania has a rich lexicon of words which may
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 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
@@ -106,11 +106,28 @@ 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: StepMania Components
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 communities and online.
you may see in StepMania/ITGmania communities and online.
--------------------------------------------------------------------------------
* Courses
Courses exist in many different forms, but in general, they take you through
@@ -171,54 +188,20 @@ you may see in StepMania communities and online.
change.
--------------------------------------------------------------------------------
2.2: StepMania Configuration
2.2: ITGmania Configuration
or "How to use the Options Menu"
--------------------------------------------------------------------------------
Learning how to properly configure StepMania can save you headaches.
Learning how to properly configure ITGmania can save you headaches.
Most themes will have the Options menu in plain sight on the Title Menu.
From there, it depends on which version of StepMania you have, as the options
menus were re-shuffled around for the StepMania 4 alphas and later versions.
This is also known as the Service Options menu. In all versions on
StepMania 5, this 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.
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 typical StepMania 3.9 Options Menu:
* Appearance Options
* Background Options
* Bookkeeping
* Center Image
* Coin Options
* Config Key/Joy Mappings
* Input Options
* Gameplay Options
* Graphic Options
* Machine Options
* Sound Options
* Profile Options
* Other Options
* Reload Songs/Courses
* Test Input
The StepMania 4.0 alpha 4 Options Menu:
* Config Key/Joy Mappings
* Test Input
* Appearance Options
* Graphics/Sound Options
* Advanced Options
* Network Options
* Profiles
* Reload Songs/Courses
sm-ssc changed this up again, making the "Options" item on the Title Menu go
to System Direction (mostly-used options), leaving the normal options menu to
the Scroll Lock key. Blame Midiman. :)
The StepMania 5.0 beta 4 Options Menu:
The StepMania 5 and ITGmania Options Menu:
* Calibrate Audio Sync
* Select Game
* Config Key/Joy Mappings
@@ -238,7 +221,7 @@ The StepMania 5.0 beta 4 Options Menu:
--------------------------------------------------------------------------------
2.2.0: Configuring Keys
--------------------------------------------------------------------------------
Controller mappings in StepMania are configured in the Config Key/Joy Mappings
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.
@@ -284,20 +267,8 @@ and leave the screen. Choosing "Cancel" will do neither, leaving you on the scre
--------------------------------------------------------------------------------
With that in mind, it's time to answer some questions using this knowledge.
Q: How do I disable the menu timer?
A: Where you go depends on the version of StepMania you use.
[3.9] Machine Options
[4.0 alphas] Advanced Options
It will be the first option on each.
[5.0] UI Options, third option from the top.
Q: How do I play forever, without game overs?
A: Turn on Event Mode. Where you go depends on the version of StepMania you use.
[3.9] Coin Options
[4.0 alphas] Advanced Options, a bit down the page.
[5.0] Arcade Options, bottom of the page.
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
@@ -306,33 +277,29 @@ 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.
It appears in different locations between StepMania versions:
[3.9] Gameplay Options
[4.0 alphas] Advanced Options, a bit down the page.
[5.0] Advanced Options, 8th option from the top.
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 StepMania will be adding/removing things to it. Well, not
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 OS X. Because of those problems, installing content in
the main StepMania folder is no longer the correct thing to do.
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 StepMania 5 is the User Data folder.
The correct place to install content on ITGmania is the User Data folder.
The exact location is different for each platform.
Windows: %APPDATA%/StepMania 5.1/
Linux: ~/.stepmania-5.1/
OS X: ~/Library/Application Support/StepMania 5.1/
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.
OS X additionally has ~/Library/Preferences/StepMania 5.1/ for storing preferences.
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
@@ -359,9 +326,8 @@ 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 StepMania on the command line/terminal.
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.
Also, this may or may not exist in your version of StepMania.
--------------------------------------------------------------------------------
2.3.1: Installing Song Files
@@ -373,10 +339,10 @@ 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 OS X), you can double
click on the .smzip file and the StepMania tools will handle it.
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 StepMania.
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.
@@ -427,7 +393,7 @@ User Data folder\
2.3.2: Installing Noteskins/New Gametypes
--------------------------------------------------------------------------------
NoteSkins change the appearance of the arrows. They are also linked with getting
other gametypes supported in StepMania.
other gametypes supported in ITGmania.
The noteskin installation process looks something like this:
User Data folder\
@@ -456,7 +422,7 @@ If it is in a .smzip, you can put it in the Packages directory:
User Data folder/
Packages/
MyTheme.smzip
and StepMania will automatically read it.
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.
@@ -479,24 +445,15 @@ 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 beta 1, or beta 2
if you are a themer and you are working on that theme to make it work with
StepMania 5 beta 4.
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.
================================================================================
Chapter 3: StepMania 5
3: Frequently Asked Questions
================================================================================
The modern StepMania 5 originally began life as sm-ssc, a fork of StepMania 4
alpha 5 (later renamed to StepMania 5 after the reboot of SM4). sm-ssc was a fork
focused on adding features for theming, but also tried to make the process of
dealing with StepMania a little easier.
--------------------------------------------------------------------------------
3.1: Frequently Asked Questions about StepMania 5
--------------------------------------------------------------------------------
Q: How do I keep my background videos/images from being stretched/distorted?
A: StepMania 5 has a preference for this, the "Set BG Fit Mode" option on the
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
@@ -518,14 +475,14 @@ 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 OS X Save/ will actually be under ~/Library/Preferences/StepMania 5/.
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 StepMania 5?
A: Create a new profile in StepMania 5. The profile's folder will be
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,
@@ -535,28 +492,20 @@ Q: I have some scores in one profile and some other scores in another profile,
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 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.
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
================================================================================
http://www.stepmania.com/forums/ is the official StepMania forum.
Use this for asking questions and generally posting about StepMania.
Please search the forums for threads that cover your question before making a
new thread.
https://github.com/stepmania/stepmania/issues is the bug tracker list.
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.
#stepmania-devs on irc.freenode.net is the IRC channel where the devs hang out.
Use this to chat with the devs and discuss StepMania related things.
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.
@@ -577,13 +526,12 @@ go through a couple requests for more information.
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 problems with any theme other than the default theme.
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.
Spending time in the developer IRC channel discussing issues can help a lot.
If you are a skilled programmer, implementing the feature and submitting a pull
request is a good way to get it added to StepMania 5. See github's instructions
on forking a repository and submitting a pull request.
request is a good way to get it added to ITGmania. See github's instructions on
forking a repository and submitting a pull request.