239 lines
15 KiB
Markdown
239 lines
15 KiB
Markdown
# Библиотека первоапрельских розыгрышей для форумов MyBB
|
||
|
||
Базовое использование:
|
||
|
||
```html
|
||
<!-- Первоапрельские шутки -->
|
||
<script src="https://static.kozhilya.ru/script/april-fools.min.js"></script>
|
||
<script>
|
||
// Установка настроек системы
|
||
window.AprilJokes.settings = {
|
||
// ...
|
||
};
|
||
</script>
|
||
<!-- Конец первоапрельских шуток -->
|
||
```
|
||
|
||
---
|
||
|
||
## Полный список шуток
|
||
|
||
- `shake` — **Форумо-трясение**. Страница форума начинает трястись.
|
||
- `mirror` — **Зеркало**. Элементы форума отражаются... По крайней мере, пытаются.
|
||
- `carnival` — **Карнавал**. Аватарки приобретают интересные цвета.
|
||
- `humanitarian_hell` — **Ад гуманитария**. Все "тся" заменяются на "ться", а все "ться" на "тся".
|
||
- `crazy_letters` — **Мама, Я сОшЛа С уМа!** иМеНа ЗаБоРчИкОм
|
||
- `letter_chaos` — **Буквенный хаос**. Все буквы в словах, кроме первой и последней, перемешены.
|
||
- `cursor` — **Красивые курсоры**. Эффекты, следующие за курсором.
|
||
- `stupid_title` — **Глупые статусы**. Каждому пользователю даётся новый глупый статус.
|
||
- `inverted_scroll` — **Обратная гравитация**. Скролл в обратную сторону.
|
||
- `latinization` — **Латинизация**. Все символы на странице или только в постах или еще где-то местами - латиницей вместо кириллицы и наоборот
|
||
|
||
---
|
||
|
||
## Тестирование шуток
|
||
|
||
Что бы проверить работу системы, вы можете включить "режим тестера". Для этого добавьте свой `UserID` в настройку `core.testers`:
|
||
|
||
```js
|
||
window.AprilJokes.settings = {
|
||
// ...
|
||
core: {
|
||
testers: [ 2, 3, 1186 ],
|
||
},
|
||
// ...
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## Настройка шуток
|
||
|
||
Настройка шуток происходит при присвоении объекта `window.AprilJokes.settings`.
|
||
Это присвоение должно произойти **после** загрузки скрипта.
|
||
|
||
Для всех шуток определены 2 общих поля:
|
||
|
||
```js
|
||
window.AprilJokes.settings = {
|
||
// ...
|
||
example: {
|
||
/**
|
||
* Активность шутки.
|
||
* Установите это значение `false`, что бы отключить шутку.
|
||
* Если `true`, то шутка будет обработана как обычно.
|
||
*/
|
||
enabled: true,
|
||
|
||
/**
|
||
* Вероятность срабатывания в процентах.
|
||
* Если установлено значение `100`, шутка будет срабатывать всегда.
|
||
* Если установлено значение `0`, шутка никогда не сработает.
|
||
* Лучше отключать шутку, используя enabled = false!
|
||
*/
|
||
chance: 20,
|
||
},
|
||
// ...
|
||
};
|
||
```
|
||
|
||
Полный список настроек с объяснениями вы можете посмотреть в файле [`settings.example.js`](./settings.example.js). Также представлен файл [`settings.compact.js`](./settings.compact.js), который также содержит все настройки, но без комментариев.
|
||
|
||
При этом, объективно, вставлять весь этот код в HTML-начало может быть "немного" неудобно, поэтому вы можете скачать код (кнопка "Raw" над файлом), изменить его, и загрузить в файлы форума, подключив скрипт таким образом:
|
||
|
||
```html
|
||
<!-- Первоапрельские шутки -->
|
||
<script src="https://static.kozhilya.ru/script/april-fools.min.js"></script>
|
||
<script src="https://forumstatic.ru/files/$$$$/$$/$$/$$$$$.js"></script>
|
||
<!-- Конец первоапрельских шуток -->
|
||
```
|
||
|
||
Заметьте, что во всех примерах приведены значения настроек по умолчанию. Вы _можете_ удалять строки, значения по умолчанию которых вас устраивают.
|
||
|
||
Если вас интересует только несколько шуток, вы можете использовать метод `disableAll()`, что бы выключить выполнение всех шуток, а потом включать отдельные шутки через установку настройки `enabled`:
|
||
|
||
```js
|
||
window.AprilJokes.disableAll();
|
||
|
||
window.AprilJokes.settings = {
|
||
// ...
|
||
example: {
|
||
enabled: true,
|
||
// ...
|
||
},
|
||
// ...
|
||
};
|
||
```
|
||
|
||
Обратите внимание, что метод `disableAll()` должен быть вызван _до_ установки настроек `settings`, иначе заданные значения `enabled` будут сброшены.
|
||
|
||
Так же есть метод `window.AprilJokes.enableAll()`, который включает все шутки, в том числе отключённые по умолчанию.
|
||
|
||
---
|
||
|
||
### Настройка `shake` (Форумо-трясение)
|
||
|
||
Тряска элементов происходит путём изменения перечисленных направлений `margin` на значение ±`force` от стандартного значения.
|
||
|
||
> **Важно**: эта шутка может вызвать дискомфорт у пользователей. Настоятельно рекомендуется оставить вероятность срабатывания шутки (`chance`) очень низкой, что бы у пользователей была возможность избавиться от шутки простым обновлением страницы! Вариант отключить шутку (`enabled: false`) тоже вариант.
|
||
|
||
---
|
||
|
||
### Настройка `mirror` (Зеркало)
|
||
|
||
Элементы форума отражаются по весьма специфичному алгоритму... И из-за этого, шутка может работать _очень_ плохо на некоторых дизайнах, поэтому данная шутка по умолчанию **отключена**
|
||
|
||
Для того, что бы попробовать, сработает ли шутка для вашего дизайна, используйте в консоли разработчика:
|
||
|
||
```js
|
||
window.AprilJokes.start("mirror", true);
|
||
```
|
||
|
||
Так же можете [посмотреть](./src/jokes/mirror.ts#L16) на метод `MirrorJoke.start`, что бы узнать как именно происходит отражение.
|
||
|
||
---
|
||
|
||
### Настройка `cursor` (Красивые курсоры)
|
||
|
||
Используются курсоры, предложенные в библотеке `tholman/cursor-effects` от Tim Holman ([Github](https://github.com/tholman/cursor-effects), [сайт](https://tholman.com/cursor-effects/)).
|
||
|
||
Код предусматривает, что одновременно активировано не более 1 курсора из этой библиотеки. Так же для каждого курсора установлен свой шанс срабатывания, однако из-за необходимости активации строго одного эффекта, предусмотрено использование весового коэффициента `weight`: если говорить просто, то чем больше это значение, то тем больше шанс срабатывания эффекта относительно других эффектов.
|
||
|
||
Так же для каждого эффекта определена настройка `enabled`, позволяющая отключить эффекты, и метод `disableAll` для отключения эффектов:
|
||
|
||
```js
|
||
window.AprilJokes.jokes.cursor.disableAll();
|
||
```
|
||
|
||
---
|
||
|
||
### Настройка `stupid_title` (Глупые статусы)
|
||
|
||
> **Важно**: этот блок может быть чрезвычайно капризным из-за особенностей хранения данных, особенно блок `variants`. Изменяя его, строго следуйте этой инструкции, иначе скрипт может перестать работать ожидаемым образом.
|
||
|
||
Данная шутка генерирует статус из случайных слов. За счёт использования псевдослучайного генератора, хеширования и привязки к времени UTC, ожидается что все пользователи одновременно будут видеть один и тот же статус для каждого пользователя, при этом он меняется каждые `change_frequency` минут. Установите это значение равным `0`, что бы статус генерировался при каждом обновлении страницы.
|
||
|
||
Для настройки списка слов используется функция `BuildStupdiTitleVariant`, которая преобразует список слов во внутренний формат скрипта. Настоятельно рекомендуется использовать именно её, а не записывать параметры напрямую:
|
||
|
||
```js
|
||
window.AprilJokes.settings = {
|
||
// ...
|
||
stupid_title: {
|
||
// ...
|
||
variants: {
|
||
adj: {
|
||
...window.AprilJokes.settings.stupid_title.variants.adj,
|
||
...BuildStupidTitleVariant(true, "скромный, шутливый, !грубый"),
|
||
...BuildStupidTitleVariant(false, "скромная, шутливая, !грубая"),
|
||
},
|
||
noun: {...window.AprilJokes.settings.stupid_title.variants.noun},
|
||
verb: {...window.AprilJokes.settings.stupid_title.variants.verb},
|
||
place: {...window.AprilJokes.settings.stupid_title.variants.place},
|
||
adv: {...window.AprilJokes.settings.stupid_title.variants.adv},
|
||
p: {...window.AprilJokes.settings.stupid_title.variants.p},
|
||
},
|
||
// ...
|
||
},
|
||
// ...
|
||
};
|
||
```
|
||
|
||
Обратите внимание на конструкции вида `{ ...something }` — эта конструкция позволяет перенести все поля нескольких старых объектов в один новый. При этом, если в двух объединяемых объектах есть совпадающие значения, то будет сохранено последнее.
|
||
|
||
Говоря проще: добавляйте ваши настройки _после_ строки вида `...window.AprilJokes.settings.stupid_title.variants.adj`, что бы ваши настройки не были перезаписаны.
|
||
|
||
Метод `BuildStupdiTitleVariant` принимает 2 аргумента:
|
||
|
||
- `gender` — определённый род для генерации. Используйте `true` для мужского рода, `false` для женского и `null`, если добавляемые варианты могут использоваться в обоих случаях.
|
||
- `words` — строка, со списком вариантов через запятую. В качестве вариантов могут быть слова из русских или английских букв, пробелов или дефисов, то есть можно использовать `"..., почему-то и зачем-то , ..."` и `почему-то и зачем-то` будет воспринят как один вариант. Также варианты можно модифицировать, добавив один или несколько модификаторов:
|
||
- `!` отключает использование слова. Этим модификатором можно отключать слова из списка по умолчанию (см `!грубый` в примере выше).
|
||
- `%` помечает слово как редкое. Шанс его использования понижается в 2 раза.
|
||
- `^` помечает слово как частое. Шанс его использования повышается в 2 раза.
|
||
- `$` помечает слово как грубое. Такие слова не будут отображаться, если в настройках отключена соответсвующая настройка `rude`.
|
||
|
||
Полный список слов по умолчанию вы можете посмотреть [в Google Таблице](https://docs.google.com/spreadsheets/d/1MJIfENqy7a9DczRj38c34t27ZQtEmBSi/edit?usp=sharing&ouid=112152128398997742033&rtpof=true&sd=true) или [в исходном файле](./src/data/stupid_title_variants.ts).
|
||
|
||
---
|
||
|
||
## Разработка дополнений
|
||
|
||
Использование для тестирования:
|
||
|
||
```html
|
||
<!-- Первоапрельские шутки: версия для разработчиков -->
|
||
<script src="https://static.kozhilya.ru/script/april-fools.js"></script>
|
||
<script>
|
||
// Установка настроек системы
|
||
window.AprilJokes.settings = {
|
||
// ...
|
||
};
|
||
|
||
// Создание новой шутки
|
||
window.AprilJokes.addCustom(
|
||
// ID шутки
|
||
"alert",
|
||
|
||
// Вызываемая функция шутки
|
||
(settings) => {
|
||
alert(settings.text);
|
||
},
|
||
|
||
// Стандартные настройки
|
||
{
|
||
title: 'Название шутки',
|
||
description: 'Описание шутки',
|
||
enabled: true,
|
||
chance: 30,
|
||
text: "Fooled!",
|
||
}
|
||
);
|
||
|
||
// Запуск шутки
|
||
// true - отключает проверки случайности
|
||
window.AprilJokes.start("alert", true);
|
||
</script>
|
||
<!-- Конец первоапрельских шуток: версия для разработчиков -->
|
||
```
|
||
|
||
Обратите внимание на то, что имя скрипта здесь `april-fools.js` (в стандартном примере — `april-fools.min.js`). Эта версия скрипта обновляется чаще, а также позволяет видеть относительно читабельный код в DevTools.
|