new manual.tex

This commit is contained in:
p.kosyh 2011-03-11 13:30:53 +00:00
parent 8da3591e75
commit 84c3f4ef34

View file

@ -30,9 +30,7 @@
\makeindex
\begin{document}
%Поддержка LaTeX оставлена в качестве костыля. Справочник _намного_ лучше выглядит в XeTeX.
%Совершенно Недокументированные Модули: goto, input, kbd
%Добавить в документацию: theme, click, format (dash-para-quotes), hideinv, prefs, timer,xact,dbg,hotkeys,snapshots
%Справочник _намного_ лучше выглядит в XeTeX!
\title{Справочное пособие по INSTEAD}
\author{Александр Яковлев\\oreolek@jabber.ru \and \textit{при участии Петра Косых}\\\textit{gl00my@jabber.ru}}
@ -979,7 +977,7 @@ require "para"
require "dbg"
\end{verbatim}
Информацию об использовании модулей смотрите на \href{http://instead.syscall.ru/wiki/ru/gamedev/modules}{вики} INSTEAD.
Информацию об использовании модулей смотрите на \href{http://instead.pinebrush.com/wiki/ru/gamedev/modules}{вики} INSTEAD.
\section{Трюки}
\subsection{Переопределение стандартных функций и объектов}
@ -1065,7 +1063,7 @@ SDL-INSTEAD поддерживает простое форматирование
txttab ("позиция", [[выравнивание]])
\end{verbatim}
Зд. "позиция" выражается в пикселях либо процентах, а выравнивание может иметь значения \verb/"left",/ \linebreak \verb/"right"/ и \verb/"center"/:
Здесь <<позиция>> выражается в пикселях либо процентах, а выравнивание может иметь значения \verb/"left",/ \linebreak \verb/"right"/ и \verb/"center"/:
\begin{verbatim}
txttab("90%","right").."слово"
@ -1210,7 +1208,7 @@ iface:shell();
И запустите игру в lua: \verb/lua game.lua/. При этом игра будет работать в примитивном shell окружении. Полезные команды: ls, go, act, use.... Теоретически движок можно таким образом привязать даже к CGI окружению.
Также рекомендуется использовать модуль \verb/dbg/. После подключения этого модуля в инвентаре появится объект "отладка". Нажав на него (либо на F7), вы войдёте в диалог отладки, откуда сможете управлять игрой. Подробное описание модуля смотрите \href{http://instead.syscall.ru/wiki/ru/gamedev/modules/dbg}{здесь}.
Также рекомендуется использовать модуль \verb/dbg/. После подключения этого модуля в инвентаре появится объект "отладка". Нажав на него (либо на F7), вы войдёте в диалог отладки, откуда сможете управлять игрой. Подробное описание модуля смотрите \href{http://instead.pinebrush.com/wiki/ru/gamedev/modules/dbg}{здесь}.
\section{Создание тем для SDL-INSTEAD}
@ -1337,7 +1335,6 @@ iface:shell();
\tabParam{scr.gfx.y}{число}{ордината окна изображений, пиксели}
\tabParam{scr.gfx.w}{число}{ширина окна изображений, пиксели}
\tabParam{scr.gfx.h}{число}{высота окна изображений, пиксели}
\tabParam{win.gfx.h}{число}{синоним \texttt{scr.gfx.h}}
\tabParam{scr.gfx.mode}{строка}{режим расположения}
\hline
\end{tabular}
@ -1372,7 +1369,8 @@ iface:shell();
\tabParam{win.fnt.size}{число}{размер шрифта главного окна, пункты}
\tabParam{win.gfx.up}{строка}{путь к файлу изображения скроллера вверх для главного окна}
\tabParam{win.gfx.down}{строка}{путь к файлу изображения скроллера вниз для главного окна}
\tabParam{win.gfx.h}{число}{синоним \texttt{scr.gfx.h}}%интересно, почему для scr.gfx.w нету?
\tabParam{win.gfx.w}{число}{синоним \texttt{scr.gfx.w}}
\tabParam{win.gfx.h}{число}{синоним \texttt{scr.gfx.h}}
\tabParam{win.col.fg}{цвет}{цвет текста главного окна}
\tabParam{win.col.link}{цвет}{цвет ссылок главного окна}
\tabParam{win.col.alink}{цвет}{цвет активных ссылок главного окна}
@ -1386,6 +1384,8 @@ iface:shell();
\caption{Параметры главного окна}\label{table_param_window}
\end{table}
Параметры win.gfx.* оставлены для совместимости. Их не стоит использовать.
Координаты скроллеров могут быть равны $-1$.
\subsection{Параметры области инвентаря}
@ -1482,12 +1482,366 @@ WinVista: \verb;Users\USER\AppData\Local\instead\themes;\\
Игра может задавать собственную тему; для этого в каталоге с игрой должен лежать тот самый \verb/theme.ini/. Его формат никак при этом не меняется, просто эта тема загружается сразу после default темы вместе с игрой.
\section{Модули}
Начиная с версии 1.2.0, INSTEAD также распространяется с некоторым набором полезных модулей. Использование этих модулей очень облегчает разработку игр на INSTEAD.
Модуль подключается при помощи следующей конструкции:
\begin{verbatim}
require "имя модуля"
\end{verbatim}
в начале файла main.lua. При этом важен порядок подключения: некоторые модули могут вызывать ошибки, будучи подключёнными в неправильном порядке.
\subsection{Click}
Модуль \verb/click/ позволяет перехватывать щёлканья мышкой по иллюстрации к сцене.
При клике вызывается обработчик \verb/click/ текущей сцены, либо универсальный обработчик \verb/game.click./
Обработчик получает три параметра: объект (комната или \verb/game/) и координаты клика. Координаты — это абсцисса (\verb/x/) и ордината (\verb/y/) в системе координат оригинального (не масштабированного) изображения. То есть, если оригинальная иллюстрация имеет размер 1024x768 пикселов, но SDL-INSTEAD запущен в полноэкранном режиме 800x600, то координаты будут всё равно вычисляться в системе 1024x768. Иначе код игры пришлось бы переписывать заново для каждого возможного размера картинки.
Координаты считаются от верхнего левого угла.
\begin{verbatim}
game.click = function(scene, x, y)
p ("Click at:",x,",", y);
end
house = room {
nam = 'Дом';
pic = 'house.png';
click = function(scene, x, y)
if x > 100 and x < 120 and y > 50 and y < 90 then
goto 'street'
end
end
}
\end{verbatim}
\subsection{Dbg}
Подключение этого модуля добавляет в инвентарь объект \verb/debug/. При нажатии клавиши F7 или выборе этого объекта вы попадаете в меню, из которого можете:
\begin{itemize}
\item переходить между локациями
\item оперировать инвентарём (подбирать и бросать предметы)
\item выполнять произвольный код Lua
\item следить за состоянием объектов
\end{itemize}
Модуль является сильнейшим средством обмана игры и не рекомендуется для включения на уже выпущенных играх.
\subsection{Format, quotes, para, dash}
Модуль \verb/format/ служит для переформатирования выводимого текста согласно русской книгопечатной традиции.
Замена происходит только при выводе содержимого сцены. Замена не производится в выводе инвентаря и меню.
Модуль имеет всего 4 настройки:
Функция \verb/format.filter/ служит для задания пользовательского фильтра. Она получает текст, который будет выведен игроку.
Если настройка \verb/format.para/ установлена в \verb/true/, то в начало каждого параграфа будет вставлен небольшой отступ. Например, как в этом справочнике. Вы можете подключить модуль \verb/para/ вместо включения этой настройки.
Если настройка \verb/format.dash/ установлена в \verb/true/, то каждая последовательность символов \verb/--/ будет заменена на среднее тире (--). Вы можете подключить модуль \verb/dash/ вместо включения этой настройки.
Наконец, если настройка \verb/format.quotes/ установлена в \verb/true/, то будут производиться следующие замены: см. табл. \ref{table_quotes}
\begin{table}[ht]
\begin{center}
\begin{tabular}{|lc|}
\hline
Последовательность символов & Результат \\
\hline
\verb/<</ & <<\\
\verb/>>/ & >>\\
\verb/,,/ & ,,\\
\verb/''/ (два апострофа) & ''\\
\verb/_"/ & <<\\
\verb/"_/ & >>\\
\verb/"/ & << или >>, угадывается автоматически\\
\hline
\end{tabular}
\end{center}
\caption{Замены кавычек}\label{table_quotes}
\end{table}
В соответствии с русской типографской традицией, вложенные кавычки должны быть другого стиля: <<кавычки „кавычки внутренние” внешние>>. Тем не менее, при использовании \verb/_"/ и \verb/"_/ , результат не предсказуем до конца и может быть таким: \guillemotleft внешние кавычки \guillemotleft кавычки внутренние\guillemotright, что также допустимо.
Вы можете подключить модуль \verb/quotes/ вместо включения этой настройки.
\subsection{Hideinv}
Модуль позволяет временно отключать инвентарь. Например, вы хотите вставить в середину игры сцену-заставку, в которой от игрока не требуется управление инвентарём. Для этого эта сцена должна быть определена с атрибутом \verb/hideinv/ в значении \verb/true/:
\begin{verbatim}
require "hideinv"
happyend = room {
nam = 'Конец';
hideinv = true;
dsc = [[ Вы прошли игру! ]];
}
\end{verbatim}
Если вы хотите использовать \verb/hideinv/ не в обычной комнате, а в \verb/xroom/, то подключите модуль \verb/hideinv/ перед модулем \verb/xact/.
\subsection{Hotkeys}
При подключении этого модуля становится возможным выбирать реплики в диалогах при помощи клавиш 1-9. Так, первая реплика выбирается клавишей 1, вторая -- клавишей 2 и т.д. Настроек модуль не имеет.
\subsection{Kbd}
Модуль \verb/kbd/ служит для перехвата событий с клавиатуры.
Он содержит две функции:
Функция \verb/hook_keys/ ставит событие перехвата на клавиши, которые переданы ей в качестве параметров. Событие возникает, когда нажата \textbf{любая} из указанных клавиш. При возникновении события выполняется блок here().kbd или же, если он отсутствует, блок game.kbd. Выполняющемуся блоку передаются три параметра: self (локация или game), булево значение нажатия (true означает нажато, false -- отжато) и текст клавиши.Например:
\begin{verbatim}
hook_keys('a', 'b', 'c')
\end{verbatim}
Событие here().kbd будет вызвано при нажатии любой из клавиш a, b или c.
Клавиши передаются функции соответственно своим клавиатурным кодам, определённым в SDL. Для удобства некоторые коды клавиш приведены в табл. \ref{table_keyboard}
Чтобы снять перехват с клавиш, следует вызвать функцию \verb/unhook_keys./ Её синтаксис аналогичен предыдущей функции, значение же противоположно.
Примером использования модуля \verb/kbd/ также служит модуль \verb/hotkeys./
\newcommand{\tabKeyboard}[4]{
\texttt{#1} & #2 & \texttt{#3} & #4 \\
}
\newcommand{\tabKbd}[2]{
\texttt{#1} & #2 & & \\
}
\begin{table}[ht]
\begin{center}
\begin{tabular}{|lccl|}
\hline
\multicolumn{1}{|c}{\textbf{Ключ}} & \textbf{Клавиша} & \textbf{Ключ} & \multicolumn{1}{c|}{\textbf{Клавиша}} \\
\hline
\tabKeyboard{a}{Английская <<a>>}{[/]}{/ на цифровой клавиатуре}
\tabKeyboard{b}{Английская <<b>>}{[*]}{* на цифровой клавиатуре}
\tabKeyboard{c}{Английская <<c>>}{[-]}{- на цифровой клавиатуре}
\tabKeyboard{...}{...}{[+]}{+ на цифровой клавиатуре}
\tabKeyboard{z}{Английская <<z>>}{enter}{Enter на цифровой клавиатуре}
\tabKeyboard{0}{0}{[0]}{0 на цифровой клавиатуре}
\tabKeyboard{1}{1}{[1]}{1 на цифровой клавиатуре}
\tabKeyboard{2}{2}{[2]}{2 на цифровой клавиатуре}
\tabKeyboard{3}{3}{[3]}{3 на цифровой клавиатуре}
\tabKeyboard{...}{...}{...}{...}
\tabKeyboard{9}{9}{[9]}{9 на цифровой клавиатуре}
\tabKeyboard{return}{Enter}{[.]}{. на цифровой клавиатуре}
\tabKeyboard{escape}{Esc}{left ctrl}{Левый Ctrl}
\tabKeyboard{backspace}{Backspace}{left shift}{Левый Shift}
\tabKeyboard{tab}{Tab}{left alt}{Левый Alt}
\tabKeyboard{space}{Пробел}{right ctrl}{Правый Ctrl}
\tabKeyboard{-}{-}{right shift}{Правый Shift}
\tabKeyboard{=}{=}{right alt}{Правый Alt}
\tabKeyboard{[}{Английская <<[>>}{numlock}{Num Lock}
\tabKeyboard{]}{Английская <<]>>}{caps lock}{Caps Lock}
\tabKeyboard{\textbackslash}{\textbackslash}{scroll lock}{Scroll Lock}
\tabKbd{;}{Английская <<;>>}
\tabKbd{'}{Английская <<'>>}
\tabKbd{`}{Английская <<`>>}
\tabKbd{,}{Английская <<,>>}
\tabKbd{.}{Английская <<.>>}
\tabKbd{/}{Английская <</>>}
\tabKbd{f1}{F1}
\tabKbd{f2}{F2}
\tabKbd{f3}{F3}
\tabKbd{...}{...}
\tabKbd{f12}{F12}
\tabKbd{print screen}{Print Screen}
\tabKbd{pause}{Pause}
\tabKbd{insert}{Insert}
\tabKbd{home}{Home}
\tabKbd{page up}{Page Up}
\tabKbd{delete}{Delete}
\tabKbd{end}{End}
\tabKbd{page down}{Page Down}
\tabKbd{right}{Right (правая стрелка курсора)}
\tabKbd{left}{Left (левая стрелка курсора)}
\tabKbd{down}{Down (стрелка курсора вниз)}
\tabKbd{up}{Up (стрелка курсора вверх)}
\hline
\end{tabular}
\end{center}
\caption{Ключи некоторых часто употребляемых клавиш в SDL}\label{table_keyboard}
\end{table}
\subsection{Prefs}
Модуль \verb/prefs/ позволяет сохранять настройки игры. Сохранённые с использованием этого модуля переменные не будут потеряны при начале новой игры.
Загрузка настроек выполняется автоматически при инициализации игры (перед вызовом функции \verb/init()/).
\verb/prefs/ -- это объект, все переменные которого будут сохранены.
Методы этого объекта:
\begin{description}
\item[prefs:store()] -- сохраняет \verb/prefs/
\item[prefs:purge()] -- удаляет сохранённый \verb/prefs/
\item[prefs:load()] -- ручная загрузка \verb/prefs/
\end{description}
\subsection{Snapshots}
Снапшот — это сохранённое состояние игры.
От обычного сохранения он отличается только тем, что он управляется только разработчиком игры. Вы можете создавать сколько угодно снапшотов (тогда как сохранений может быть только 5). Пользователь может удалять снапшоты (зная, где они лежат и как выглядят), но не может их редактировать.
Сохранения можно вызывать из игры, но нельзя загружать. Сохранения доступны глобально, снапшоты — локально. Пользователь может сделать резервную копию сохранений, но не снапшотов.
Чтобы создать снапшот, следует вызвать функцию \verb/make_snapshot()./ Необязательным параметром является номер слота.
Следует помнить, что снапшот будет создан не моментально, а после завершения текущего такта игры. Иначе сохранённое состояние может оказаться противоречивым.
Чтобы загрузить сохранённый снапшот, нужно вызвать функцию \verb/restore_snapshot()./ Опять же, ей можно передать номер загружаемого слота.
Чтобы удалить сохранённый снапшот, вызывается функция \verb/delete_snapshot()./ Снапшоты занимают место на диске, и их чистка всегда полезна.
\begin{verbatim}
house = room {
nam = 'У здания',
entered = code [[ make_snapshot() ]],
dsc = 'Вы стоите перед зданием.',
}
\end{verbatim}
\subsection{Timer}
Модуль \verb/timer/ -- это удобная прослойка для управления таймером.
Метод \verb/timer:set(интервал)/ включает таймер с заданным интервалом в миллисекундах. Каждое заданное количество миллисекунд будет вызываться событие \verb/here().timer/ либо \verb/game.timer/, если в данной локации не определён этот атрибут. Чтобы отключить таймер, нужно вызвать метод \verb/timer:stop()./
Главным отличием использования модуля Timer от обычного использования объекта \verb/timer/ является то, что при использовании модуля обработчик работает в контексте stead, а не sdl-instead; то есть, вы защищены от ошибок с неправильным возвратом управления.
\begin{verbatim}
game.timer = function(s)
set_sound('gfx/beep.ogg');
p "Timer:"
p (time())
end
init()
timer:set(1000)
end
\end{verbatim}
\subsection{Theme}
Модуль \verb/theme/ позволяет менять тему в процессе игры, без редактирования файла \verb/main.lua./
Он объявляет следующие функции:
\begin{description}
\item[theme.get('имя параметра')] — чтение текущих параметров текущей темы
\item[win.geom(x, y, w, h)] — смена координат и размеров главного окна
\item[win.color(fg, link, alink)] — смена цветов текста, ссылок и активных ссылок главного окна
\item[win.font(name, size, height)] — смена параметров шрифта главного окна
\item[win.gfx.up(pic, x, y)] — смена параметров верхнего скроллера главного окна
\item[win.gfx.down(pic, x, y)] — смена параметров нижнего скроллера главного окна
\item[inv.geom(x, y, w, h)] — смена координат и размеров инвентаря
\item[inv.color(fg, link, alink)] — смена цветов текста, ссылок и активных ссылок инвентаря
\item[inv.font(name, size, height)] — смена параметров шрифта инвентаря
\item[inv.gfx.up(pic, x, y)] — смена параметров верхнего скроллера инвентаря
\item[inv.gfx.down(pic, x, y)] — смена параметров нижнего скроллера инвентаря
\item[inv.mode(mode)] — смена режима инвентаря
\item[menu.bw(w)] — смена толщины границы меню
\item[menu.color(fg, link, alink)]— смена цветов текста, ссылок и активных ссылок меню
\item[menu.font(name, size, height)] — смена параметров шрифта меню
\item[menu.gfx.button(pic, x, y)] — смена параметров значка меню
\item[gfx.cursor(norm, use, x, y)] — смена параметров курсора
\item[gfx.mode(mode)] — смена режима расположения
\item[gfx.pad(pad)] — смена отступов к скролл-барам и краям меню
\item[gfx.bg(bg)] — смена фонового изображения
\item[snd.click(name)] — смена звукового эффекта для действия
\end{description}
Если часть параметров менять не следует, то их можно заменить значением \verb/nil/.
Пример:
\begin{verbatim}
gfx.bg "dramatic_bg.png";
win.geom (nil,nil, theme.get 'scr.w', theme.get 'scr.h');
inv.mode 'disabled'
\end{verbatim}
\subsection{Xact}
Довольно много людей жаловались, что в INSTEAD очень неудобно вставлять описание объектов в описание комнат. Например, автор хочет сделать что-то подобное:
\begin{quote}
Вы входите в большой зал. На стенах висят \href{}{картины}. С потолка свешивается огромная \href{}{люстра}. Здесь очень красиво, хотя странный сильный \href{}{запах} немного портит впечатление.
\end{quote}
Чтобы написать нечто подобное в стандартном окружении INSTEAD, необходимо объявить три объекта: картины, люстра и запах. Описание локации (атрибут dsc) будет пустым, а то, что будет выводиться игроку, будет составляться из описаний предметов. Так, первые две фразы будут храниться в атрибуте dsc объекта <<картины>>, третья фраза будет принадлежать объекту <<люстра>>, а объект <<запах>> будет описывать всё остальное. При этом объекты должны добавляться в сцену в строго определённом порядке.
Чтобы описание сцены действительно хранилось в описании сцены, был написан модуль \verb/xact./ Он также позволяет делать ссылки на объекты из других объектов и реакций.
Обычная ссылка INSTEAD выглядит так:
\begin{verbatim}
dsc = "Вы входите в большой зал. На стенах висят {картины}."
\end{verbatim}
xact - cсылка выглядит так:
\begin{verbatim}
dsc = "Вы входите в большой зал. На стенах висят {pictures|картины}."
\end{verbatim}
Здесь объект pictures отвечает за картины. Ссылка на него может стоять где угодно. Ссылаться можно на сам объект или его \verb/nam./
Общий вид ссылок:
\begin{verbatim}
{объект(параметры)|текст}
\end{verbatim}
До версии 1.2.2 символом разделителя было двоеточие (\verb/:/). После версии 1.2.2 символ разделителя задаётся полем \verb/stead.delim/; по умолчанию он задан вертикальной линией (\verb/|/).
Также модуль \verb/xact/ содержит несколько упрощённых реализаций объектов:
Объект \verb/xact/ описывает простейшую реакцию. Это объект — декорация, он может только выполнять одну функцию, когда к нему обращаются. Объект задаётся так:
\begin{verbatim}
hello = xact('nam',code[[do_something()]])
\end{verbatim}
Первый параметр функции \verb/xact/ имя объекта, второй реакция. Реакция может быть строкой, функцией или \verb/code/.
Комната \verb/xroom/ отличается от обычной тем, что имеет атрибут \verb/xdsc/. Если его задать, то он будет выведен после описания сцены, вместо описаний объектов.
Функцию \verb/xdsc('имя атрибута')/ можно вызывать несколько раз, чтобы вывести на экран дополнительные описания.
\begin{verbatim}
main = room {
dsc = [[Я в комнате.]];
xdsc = [[ Я вижу {apple|яблоко} и {knife|нож}. ]];
other = [[ Еще здесь лежат {chain|цепь} и {tool|пила}.]];
obj = {
xdsc(),
xdsc 'other',
xact('apple',[[Красное наливное яблочко.]]),
'knife', 'chain', 'tool',
}
}
\end{verbatim}
\section{Дополнительные источники документации}
Вот и закончен справочник по INSTEAD. Напомню, что INSTEAD расшифровывается (и переводится) как <<Интерпретатор простых текстовых приключений>>. Официальная документация находится в каталоге doc и поставляется с instead. Дополнительную информацию вы можете получить в Интернете:
\begin{itemize}
\item \href{http://instead.googlecode.com/}{Сайт программы}
\item \href{http://instead.syscall.ru/forum}{Форум программы}
\item \href{http://instead.pinebrush.com/}{Форум программы}
\end{itemize}
Кроме того, полезно будет посмотреть Subversion-репозиторий INSTEAD, где хранится исходный код самого движка и код нескольких полезных трюков, которые не пакуются в релиз для Windows\footnote{Так как релиз для Linux выходит в исходных кодах и заведомо меньше по размеру, то дополнительные исходные коды из него не вырезаются.}. Вы также можете найти несколько полезных руководств (в том числе и это) в подкаталоге doc/ программы.